Localization/Translation

General usage

Generating localizations in extensions is done per package via a translation YAML file found in the ./pkg/<extension-name>/l10n directory. If a translation is not included in the user's selected language, it will fall back to English.

As an example, you can create file called ./pkg/<extension-name>/l10n/en-us.yaml with the following translation strings:

Form fields are conventionally defined in translations as <some prefix>.<field name>.{label,description,enum options if applicable} e.g.

account:
  apiKey:
    description:
      label: Description
      placeholder: Optionally enter a description to help you identify this API Key

And can be used in the following manner:

In HTML

<t k="<path to localisation>" />
{{ t("<path to localisation>") }}

t can be exposed via adding the i18n getter as a computed property with ...mapGetters({ t: 'i18n/t' }) using the Options API.

t can be exposed in the following manner using the Composition API:

const store = useStore();
const { t } = useI18n(store);

Many components will also accept a localisation path via a value-key property, instead of the translated text in value.

In JS/TS

this.t('<path to localisation>')

A localisation can be checked with

this.$store.getters['i18n/exists']('<path to localisation>')

this.$store.getters['i18n/withFallback']('<path to localisation>', null, '<fallback>'))

If you wanted to have the string Optionally enter a description to help you identify this API Key rendered, then <path to localisation> would be account.apiKey.description.placeholder.

In the HTML example with the above key, the usage should be:

<t k="account.apiKey.description.placeholder" />
{{ t('account.apiKey.description.placeholder') }}

Using variables in paths

In Javascript files, variables in localisation paths must be wrapped in quotation marks when the variable contains a slash.

For example, if we want to dynamically fill in the description of a resource based on its type, we can use a type variable when referencing the localisation path to the description:

{
  description: this.t(`secret.typeDescriptions.'${ type }'.description`),
}

In this case, the quotation marks are required because some Secret types, such as kubernetes.io/basic-auth, include a slash.

Advanced usages

Messages and number formatting uses ICU templating for very powerful pluralization and customizing.