Internationalization

This is providing a centralized way of translating string to any language as long as opts.translate and opts.getTranslations callbacks provide translations for them.

I18n class must be treated as singletone and should never be instantiated in any way except calling provideI18n in setup stage. It must be called as early as possible in root component of Vue app for useTranslator to function. If other object properties are required (e.g. to change locale) - injectI18n should be used.

useTranslator composable should be used to translate strings.

Demo caveats

Because there is no parent component to use - i18n can't be injected. Instead - useTranslator composable has optional argument where i18n can be passed. This should not be used without special reason. Real-world applications should use useTranslator with groupKey parameter only, and get i18n instance through injection.

<template>
  <div class="spaced-out">
    <div>
      Generic:
      <div>{{ t('Text to translate').value }}</div>
    </div>
    <div>
      Pluralization:
      <div>{{ tc(['{count} original', '{count} originals'], 1).value }}</div>
      <div>{{ tc(['{count} original', '{count} originals'], 2).value }}</div>
    </div>
    <ci-button @click="buttonAction">Button</ci-button>
  </div>
</template>
<script>

export default {
  setup () {
    const fakeTranslations = [{
      text: 'Text to translate',
      translated: 'Translated text',
      parametrized: []
    }, {
      text: '{count} original',
      translated: '{count} translation',
      parametrized: ['{count} translation', '{count} translations']
    }, {
      text: 'Hidden initially',
      translated: 'Still translated',
      parametrized: []
    }]
    const i18n = provideI18n(null, {
      getTranslations: (locale, groupKey) => new Promise((resolve) => {
        resolve({ id: groupKey, locale, translations: fakeTranslations })
      }),
      translate: (texts, locale, groupKey) => new Promise((resolve) => {
        resolve({ id: groupKey, locale, translations: fakeTranslations })
      }),
    })

    const { t, tc, ta } = useTranslator('ds', i18n)

    async function buttonAction () {
      alert((await ta('Hidden initially')).value)
    }

    return {
      t, tc, ta, buttonAction
    }
  }
}
</script>
<style>
.spaced-out {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
</style>

groupKey concept

To not store all strings for all of our applications in memory of each application - groupKey should be used to group translations.

useTranslator composable

Main tool to be used for application translation. If application wasn't setup for translations - see Setup section to get started. groupKey should be passed that will be used for getting previously translated strings or save new ones.

• init - gets existing translations for groupKey and stores it in memory. Returns promise, so it can be awaited. Might be usefull to prevent showing untranslated text.
• t - main method for getting translation. Returns reactive string, that represents translation of text argument. It will either return translation immediately if translation is not present, or temporary show original string that is passed in as argument. Value of reactive string will be immediately changed once translation is recieved from server.
  • Arguments
    • text: string - text to be translated.
  • Returns: Ref<string>
• tc - method to get string that depends on pluralization. Has same properties as t.
  • Arguments
    • text: string[] - text to be translated. Should contain {count}. it is used as a placeholder for a number that will be inserted. Should contain the singular and plural forms of the word in initial language to be used as defaults.
    • count: number - count, that will replace {count} placeholder. Also will be used to select correct translation version based on the number.
• ta - async method to get translation. Can be used for cases where a translation is necessary for non-reactive text, must be awaited.
  • Arguments
    • text: string - text to be translated.

Setup

1. provideI18n must be called as soon as possible and insure that no translation is requested before i18n is provided
2. translate and getTranslations callbacks must be provided in second argument. See details below.
3. Use useTranslator in any child component to translate strings
4. In case of need to translate string in root component itself - provide i18n instance that is returned by provideI18n to composable.

provideI18n

• targetLocale - initial locale. If not set - brower language will be used. Can be changed by using setLocale (see reference to i18n below).
• opts.translate - async callback to translate set of strings. Will be used when UI requests string translation that is not yet stored in memory.
  • Arguments:
    • texts: string[] - array of strings to be translated.
    • locale - target language or locale.
    • groupKey - contextual key. API will use it to group strings by context. (see more details above).
  • Expected resolved value: instance of TranslationBatch
• opts.getTranslations - async callback to get translations that are stored in database. Will be used once whenever useTranslator will be used with new groupKey parameter. Used to initiate translations before they are used. Can be used in router navigation guards to pre-load existing translations.
  • Arguments
    • locale - target language or locale.
    • groupKey - contextual key. API will use it to group strings by context. (see more details above).
  • Expected resolved value: instance of TranslationBatch.

injectI18n

Returns provided i18n instance.

i18n class instance

• setLocale - wipes out stored translations and sets new target locale.

Other methods are for internal use only or for some edge case handling. For all translation purposes useTranslator composable should be used.