@telefonica/la-content-i18n
v1.1.0
Published
Library to handle localization in React apps.
Downloads
9
Readme
@telefonica/la-content-i18n
Library to handle localization in React apps.
$ npm install @telefonica/la-content-i18n
Usage
Wrap your component tree in a
<I18nProvider>
, with thei18n
attribute set to the instance resulting frominit()
.languageImporter
is an async function called successively withlocale
andnamespace
names. It's your responsibility to load the.json
files with translations given these. It is okay to return a failingPromise
if the.json
file can't be found.import { init, I18nProvider } from '@telefonica/la-content-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 ani18nKey
prop identifying said string. You can also call theuseTranslation()
hook and thet()
function it returns.import { Trans } from '@telefonica/la-content-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 theuseTranslation()
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 islocales/{{locale}}/{{ns}}.json
.$ npx i18n extract -l en,es
Translate the extracted
.json
filesDone!
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.
Architecture
This library is a wrapper on top of i18next
and
react-i18next
, with some options already set by default. You can read their
documentation to learn more about how it works.
This wrapper:
Initializes
i18next
andreact-i18next
(./src/index.ts
):- with the browser-based language detector
- with a custom manual backend (
./src/ManualBackend.ts
) that just calls a user-provided functionWhy? So the caller of the API can
import()
the translation files and have them handled by their bundler (i.e.webpack
). - with automatic debugging for production
- some more useful options (check i18next options documentation )
Re-exports
react-i18next
interfaces<Trans>
anduseTranslation()
(the rest are not useful for our usecase) (./src/react.sx
)Provides a CLI for extracting translations from code into the locale files (through
babel-plugin-i18next-extract
) (./src/bin.ts
):- It manually runs babel with the
babel-plugin-i18next-extract
plugin on the specified files, already prepared to accept the re-exported entrypoints from this package.
- It manually runs babel with the