The useTranslation hook

The useTranslation hook is what you'll be interacting with the most on the front end. This powered by TranslationContext, so all instances of useTranslation hook are using the same locale in sync. Before using the useTranslation hook, make sure you've set up the TranslationProvider in the highest component.

useTranslation has three tools to use:

• ix() - The translation wrapper. Wrap any text with ix, and it will translate the text into any language set by the locale.
• locale - The current locale set in the hook.
• setLocale() - Function to set the locale of the hook.

Translation with ix()

ix is the translation wrapper. Simply wrap the text that you want to translate in the ix wrapper.

import { Locales } from "@/i18nix/lib/types";
import { useTranslation } from "@/i18nix/translation";
 
export default function Home() {
  const { ix } = useTranslation();
  return <div>{ix("Hello world!")}</div>; // Will return the translated text into the current locale
}

When you wrap text around ix, the framework turns the text that you wrapped into a key. This key is then mapped to the translated text of that key in every language. These keys and maps are then stored as JSON translation files.

String interpolation

You can inject variables and do interpolation by passing in variables as a parameter into ix

ix("Hello, my name is {fullName}.", { fullName: user.name() });

It would look like this in the translation file:

{
  "Hello, my name is {fullName}.": {
    "author": "matt@gmail.com",
    "comment": "Greeting on the home page",
    "locations": ["/components/home.tsx"],
    "value": "Hola, me llamo {fullName}."
  }
}

You can also inject React components as a variable into the string

ix("Hello, my name is {fullName}.", {
  fullName: <a href={user.url()}>{user.name()}</a>,
});

Pluralization

The framework handles pluralization by passing in a variable {count}. Any usages of {count} in your string will trigger the pluralization logic.

ix("There are {count} days left.", {
  count: getDaysLeft(),
});

This will look like this in the translation file:

{
  "There are {count} days left.": {
    "author": "matt@gmail.com",
    "comment": "Counter in the home page.",
    "locations": ["/components/home.tsx"],
    "single_value": "There is {count} day left.",
    "plural_value": "There are {count} days left."
  }
}

Currency and time translation

In the future, we plan to implement currency and time translations, and integrate that with ix().

Displaying current locale: locale

You can see the current locale set using the locale variable in the useTranslation hook.

Let's say that the Provider had initialized the locale to French Locale.FR.

import { TranslationProvider } from "@/i18nix/translation";
import { Locales } from "@/i18nix/lib/types"; // Locales are type safe
 
<TranslationProvider initialLocale={Locales.FR}>
  <Home />
</TranslationProvider>;

You can access the hook's locale by reading locale from the useTranslation hook.

import { useTranslation } from "@/i18nix/translation";
 
export default function Home() {
  const { locale } = useTranslation();
  console.log(locale); // will display "fr" for French
}

Changing locale with setLocale()

You can use the function setLocale() to change the locale. However, we recommend that if you have

import { useTranslation } from "@/i18nix/translation";
import { Locales } from "@/i18nix/lib/types"; // Locales are type safe
 
const { setLocale, locale } = useTranslation();
setLocale(Locales.Spanish); // Changes the locale to Spanish. The change is reflected globally
console.log(locale); // prints "es" for Spanish

However, if you have i18n subpath routing set up, it is highly recommended to redirect/refresh the page to have the new locale in the URL path.