Supporting default translation values

[halilb]

Thanks for the great library @ivanhofer!

My colleague told me about Elastic's kbn-i18n library while I was integrating this one into our project.

It has one requirement to keep the default English version right next to the template where the translation is used. This is because they want to fuzzy-find English texts in the project and jump right at where it's used. It also adds more context to template files so devs would know better what they're looking at.

One of our technical requirements is to have default messages in the templates themselves, and those messages will always be in English, so we don't have to keep en.json file in repository. We can generate that file from defaultMessages defined inline.

It comes with a few trade-offs so we're not sure if using default values is worth the effort. So I wanted to ask you before going forward with this decision: can you think of a way to build it as a wrapper of typesafe-i18n?

[ivanhofer]

Hi @halilb,

I'm not sure if I understood everything correctly. I try to summarize it:

1. keep translations near the component that uses the translation
   typesafe-i18n uses the opposite approach and stores translations in a central place (./src/i18n/[locale]/...). You could still go with the other approach but it is a bit of a hack. Since typesafe-i18n builds on top of usual TypeScript files, you can do the following:

   store translations near your components
   /src/components/login/translations.ts

   export const en = {
      usernameLabel: 'username:',
      passwordLabel: 'password:',
      cta: 'login'
   }
   
   export const de= {
      usernameLabel: 'Benutzername:',
      passwordLabel: 'Passwort:',
      cta: 'Einloggen'
   }

   and import them in your dictionary
   /src/i18n/en/index.ts

   import type { BaseTranslation } from '../i18n-types'
   import { en as login } from '../../components/login/translations'
   
   const en: BaseTranslation = {
      // some base translations
      continue: 'Continue',
      // component-specific translations
      components: {
         login,
         // ... other components
      }
   }
   export default en

2. use the base translation as a key
   Most libraries suggest to organize your translations via keys

   {
      'hello': 'Hello {name}!'
   }
   
   <h1>{LL.hello({ name: 'John' })}</h1>

   instead if inlineing them

   const name = 'John'
   
   <h1>{LL`Hello ${name}!`}</h1>

   There is a middle-way you could use with typesafe-i18n (and most other libraries):
   Use the message itself as a key.

   <h1>{LL['Hello {name}!']({ name: 'John' })}</h1>

   But you still would need to add it to the base translations

   {
      'Hello {name}!': 'Hello {name}!'
   }

I'm not sure if this answers your questions 😅
Let me know if something is still unclear.

[halilb]

Thanks for the quick reply @ivanhofer! I forgot to add an example that could have made it clearer.

// src/i18n/en/index.ts
export const en = {
   // Not repeated here as it's defined with the `defaultText` value
   hello: '{defaultText}',
}

// src/i18n/de/index.ts
export const de= {
  helllo: 'Hallo {name}. Wie gehts?',
}

// src/some_component.ts
const { LL } = useI18nContext();
const helloText = LL.hello({
  defaultText: 'Hello {name}. How are you?',
  name: 'John',
});

// Should print 'Hello John. How are you?' for English
console.log(helloText);

The benefit here is I'll jump right at some_component when I fuzzy-search How are you? in my codebase.

Trade-offs are:

• We'll always load English translations into the client so it might increase the network traffic for non-English users.
• It gets harder to provide a single translation file in English to translators.

We're also trying to understand if we're overengineering the problem here so I'd love to hear your opinions.

[ivanhofer]

Ah, now I got it. Thanks for the example.

I can understand that jumping to the actual text directly inside the component would increase DX a lot when searching for text snippets.

The example above is not possible with typesafe-i18n because the generator needs to parse the base translation file (en) in order to create the i18n-types.ts file.

Loading always the english translation on top of the actual locale is far from ideal, but would probably not really affect the performance of your application.

In theory you could write a vite (or other built-tool) plugin that extracts all defaultTexts and writes them to the base translation file. But I'm not sure if it is worth the effort.

[halilb]

I just realized there is a VSCode plugin that solves some of the pain points I described: https://github.com/lokalise/i18n-ally We are using neovim and there is no such library for that, unfortunately.

One thing that'd help us could be removing the translation from RooTranslation types so we can jump into TranslationFunctions when we fuzzy-find a text.

Example output:

type RootTranslation = {
  server: {
    /**
     * You need to post a comment first to be able to complete this lesson.
     */
    needCommentFirst: string;
  };
};

export type TranslationFunctions = {
  server: {
    /**
     * You need to post a comment first to be able to complete this lesson.
     */
    needCommentFirst: () => LocalizedString;
  };
};

Is there a way to modify auto-generated RootTranslation types to remove "You need to post..." text there to prevent duplication?

[halilb]

Nice! This would do the job for our purposes. Do you consider making it default or putting it behind a configuration option?

[ivanhofer]

I think we can make this the default behaviour. I can implement this in the coming days

[halilb]

Sounds great! Thank you @ivanhofer!

[ivanhofer]

Implemented and released in version 5.14.0 🎉

[halilb]

That's really fast! Thanks a lot, @ivanhofer. I'll try it out.