Translations management

Why?

Organizing translations using i18n and following opinionated convention for easy maintainability and good readability

How?

Setup the i18n Ally extension

We recommended using the i18n Ally (opens in a new tab) plugin for VS Code for translations management.

.vscode/settings.json

{
  "i18n-ally.localesPaths": ["src/locales"],
  "i18n-ally.keystyle": "nested",
  "i18n-ally.enabledFrameworks": ["general", "react", "i18next"],
  "i18n-ally.namespace": true,
  "i18n-ally.defaultNamespace": "common",
  "i18n-ally.extract.autoDetect": true,
  "i18n-ally.keysInUse": ["common.languages.*"]
}

Guidelines for translations

Use namespaces t('namespace:translationKey') and nesting t('namespace:this.is.nested').

const { t } = useTranslation(["account"]);
 
// Example for translations available in account.json
t("account:data.firstname.label");

For fields and data translations use a data object.

account.json

{
  "data": {
    "firstname": {
      "label": "First Name",
      "required": "First Name is required"
    }
  }
}

React integration

const { t } = useTranslation(["account"]);
 
t("account:data.firstname.label");
t("account:data.firstname.required");

For user feedbacks, use a feedbacks object with actionSuccess & actionError keys containing each title and description (optional).

account.json

{
  "resetPassword": {
    "feedbacks": {
      "confirmSuccess": {
        "title": "Your password has been reset",
        "description": "You can now login"
      },
      "confirmError": {
        "title": "Reset password failed"
      }
    }
  }
}

React integration

const { t } = useTranslation(["account"]);
 
t("account:resetPassword.feedbacks.updateSuccess.title");
t("account:resetPassword.feedbacks.updateSuccess.description");
t("account:resetPassword.feedbacks.updateError.title");

For user actions, use an actions object.

account.json

{
  "resetPassword": {
    "actions": {
      "send": "Send Email",
      "reset": "Reset Password"
    }
  }
}

React integration

const { t } = useTranslation(["account"]);
 
t("account:resetPassword.actions.send");
t("account:resetPassword.actions.reset");

Common

⚠️

Use the common workspace only for VERY generic translations. By default, use specific namespaces to allow easy update on large code base without unwanted side-effects.

Add new language Visual hint for environments