Skip to main content

Shared I18n

Internationalization (i18n) support for the Substrate project, built on i18next.

Features​

  • App-owned translations: Each application manages its own translation JSON files
  • Shared infrastructure: i18next initialization, React provider, and helper utilities
  • Type-safe: TypeScript support for translation keys and functions
  • React integration: Provider component and hooks for React applications
  • Standard helpers: JavaScript/TypeScript utilities for accessing translations
  • Extensible: Easy to add new languages and translation keys

Translation Key Format​

Translation keys follow the format: project.scope.purpose.term

Examples​

  • global.company.name - Shared across all projects
  • web.navigation.warning.text - Specific to the web app's navigation
  • web.home.welcome - For the web app's home page

Usage in React​

Setup​

Each application provides its own translation resources when wrapping with I18nProvider:

import { I18nProvider } from "shared-i18n";
import en from "./locales/en.json";

const resources = { en: { translation: en } };

export function App({ children }) {
  return (
    <I18nProvider resources={resources} defaultLanguage="en">
      {children}
    </I18nProvider>
  );
}

Using Translations in Components​

import { useTranslation } from "shared-i18n";

export function MyComponent() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("web.home.welcome")}</h1>
      <p>{t("global.company.tagline")}</p>
    </div>
  );
}

Changing Language​

import { useI18nContext } from "shared-i18n";

export function LanguageSwitcher() {
  const { currentLanguage, changeLanguage } = useI18nContext();

  return <button onClick={() => changeLanguage("en")}>Current: {currentLanguage}</button>;
}

Usage in Node.js/Non-React Code​

import { t, initI18n } from "shared-i18n";
import en from "./locales/en.json";

// Initialize with translation resources
await initI18n({
  resources: { en: { translation: en } },
});

// Use translations
const companyName = t("global.company.name"); // "Zero Kelvin"
const welcome = t("web.home.welcome"); // "Welcome to Zero Kelvin"

Adding New Translations​

  1. Open the translation JSON file in your application (e.g., apps/web/src/locales/en.json)
  2. Add your translation following the key format:
{
  "web": {
    "myFeature": {
      "title": "My Feature Title",
      "description": "My feature description"
    }
  }
}
  1. Use in your code:
const title = t("web.myFeature.title");

API Reference​

See the API Reference for detailed documentation of all functions and types.