la-i18n
Library to handle localization in React apps.
$ npm install la-i18n
Usage
-
Wrap your component tree in a <I18nProvider>
, with the i18n
attribute set to the instance resulting from init()
.
languageImporter
is an async function called successively with locale
and namespace
names. It's your responsibility to load the .json
files with translations given these. It is okay to return a failing Promise
if the .json
file can't be found.
import { init, I18nProvider } from 'la-i18n'
const i18n = init({
languageImporter: async (locale, namespace) => import(`../locales/${locale}/${namespace}.json`),
})
export const AppWrapper = ({ children }) => <I18nProvider i18n={i18n}>{children}</I18nProvider>
Translations will be layered. Basically, the finished strings would be something like:
const translations = {
...(await languageImporter('dev', ns)),
...(await languageImporter('en', ns)),
...(await languageImporter('en-US', ns)),
}
-
Throughout your app, wrap any translatable strings in the <Trans>
component, with an i18nKey
prop identifying said string.
import { Trans } from 'la-i18n'
import { MyHoverEffect } from './other-components'
const MyHeader = () => (
<div>
<h1>
{/* Basic usage */}
<Trans i18nKey="myheader.welcome">Hello world!</Trans>
</h1>
<p>
{/* This works! The string will reflect simple tags in the translatable messages. */}
<Trans i18nKey="myheader.subtitle">
Welcome to the <b>best</b> app in the world.
</Trans>
</p>
<p>
{/* This still works. More complex elements will be anonymized and be shown like `<0>this</0>`. */}
<Trans i18nKey="myheader.call-to-action">
Learn more about us <MyHoverEffect>now!</MyHoverEffect>
</Trans>
</p>
<p>
{/* Yep, still works! Wrap variables in an object to have it be shown as an identifier in the translatable messages. */}
<Trans i18nKey="myheader.current-user">You're currently logged in as {{ name }}.</Trans>
</p>
</div>
)
If the <Trans>
component is not enough (e.g. you need plurals), you can access a full i18next instance calling the useTranslation()
hook.
-
Call the bundled i18n
binary to extract the strings from the source files. Use the -l
parameter to pass a list of the desired locales.
The default source file glob is src/**.{js,jsx,ts,tsx,mjs,cjs}
, and the default output path is locales/{{locale}}/{{ns}}.json
.
$ npx i18n extract -l en,es
-
Translate the extracted .json
files
-
Done!
Detect/change locale
With the i18n
instance resulting from init()
or the useTranslation()
hook, you can call i18n.changeLanguage("locale")
. If you don't pass a locale, one will be detected from the user's browser.