Tool for localize application.
<span>{t("Wrong phone format", "errors")}</span>
Using npm:
$ npm install --save @sho-js/react-context-locale
You must provide locale setting and controls with LocaleProvider
:
<LocaleProvider
onSameTranslation={({currentLocale, category, value}) => `Translated string is same as key ${currentLocale}:${category}:${value}`}
onMissingTranslation={({currentLocale, category, value}) => `Missing translation ${currentLocale}:${category}:${value}`}
onLocaleChanged={(currentLocale) => console.log(`Locale changed to ${currentLocale}`)}
availableLocales={["ru", "en", "gb"]}
commonTranslations={Translations}
storage={new Storage()}
defaultLocale="en"
baseLocale="ru"
>
// ...
</LocaleProvider>
where
availableLocales
- list of available locales.baseLocale
- locale, that used as key for translation.commonTranslations
- object, that contains common translations.onLocaleChanged
- will called, when locale was changed. Optional.onSameTranslation
- will called, when translated string is same as key. Optional.defaultLocale
- locale, that will be used on did mount. Optional. Default is same asbaseLocale
.storage
- object, that implements translations storage. Optional. If not passed, will be created automatically.onMissingTranslation
- will called, when translation key does not found in storage. Optional. If not passed, string with error description will be returned.
Note: Pass storage
prop, only if you need to access it from outside, in other cases it does not needed
Translations object example:
{
"gb": {
"errors": {
"Неверный формат": "Falsches Format"
}
},
"en": {
"errors": {
"Неверный формат": "Wrong format"
}
}
}
Note: In this example ru
locale is used as base locale, so it not needed for translation.
Note: Categories name are not translatable
To register new translation, use RegisterCategory
component:
<RegisterCategory categoryName="testCategory" translations={{en: "Тест": "Test"}}>
// ...
</RegisterCategory>
In storage it will be:
{
"en": {
"testCategory": {
"Тест": "Test"
}
}
}
where
categoryName
- new category nametranslations
- object, that contains new category translations
Note: Categories must be unique. If it doesn't, last registered category will be used and other will be deleted
To translate string you must wrap it into the Translator
component:
<RegisterCategory categoryName="testCategory" translations={Translations}>
<span>
<Translator category="mainPage" render={(translated: string) => <span data-name={translated}/>}>
Тестовый перевод
</Translator>
</span>
</RegisterCategory>
where
category
- category name. Optional. In this case default aretestCategory
render
- function, that return executing result toTranslator
render method. Optional. If not passed, string will be returned
Or you can also use t
function:
<span>{t("Тестовый перевод", "mainPage")}</span>
Note: t
function just return Translator
component
For controlling switching locale, use SingleLanguageSwitcher
or MultipleLanguageSwitcher
component.
SingleLanguageSwitcher
will render single button, that will change locale in the same sequence, than locales declared in availableLocales
:
<SingleLanguageSwitcher
render={(label: string, locale: string) => <span data-locale={locale}>{label}</span>}
localeLabels={{ru: "RUS", en: "ENG", gb: "GER"}}
{...HTMLButtonProps}
/>
where
localeLabels
- label, that will be displayed in button, according to current locale. Optional. If not passed, original locale name will be displayedrender
- function, that return executing result toSingleLanguageSwitcher
render method. Optional. If not passed, string will be returned
MultipleLanguageSwitcher
will render count of buttons according to available locales length:
<MultipleLanguageSwitcher
render={(label: string, locale: string) => <span data-locale={locale}>{label}</span>}
localeLabels={{ru: "RUS", en: "ENG", gb: "GER"}}
activeClassName="is-active"
{...HTMLButtonProps}
/>
where
activeClassName
- class name that will be appending to button with according active locale. Optional. Default -active
If you need to display some markup only for specified locale, use OnLocale
component:
<OnLocale locale="en">
<span>You see this, because you selected `en` locale</span>
<OnLocale>
where
locale
- locale on which showing markup
It is only necessary to indicate the forms of the declined word in different situations:
<span>
<Translator category="mainPage" params={{n: 10}}>
There _PLR(n! 0:are no cats, 1:is one cat, other:are # cats)!
</Translator>
</span>
or
<span>
{t("There _PLR(n! 0:are no cats, 1:is one cat, other:are # cats)!", "mainPage", {n: 10})}
</span>
where
params
- contains string arguments_PLR(*argument*! ...rules)
- plural string
Will render:
<span>There are 10 cats!</span>
Available rules:
Rule | Meaning |
---|---|
0 | means zero |
1 | corresponds to exactly 1 |
one | 21, 31, 41 and so on |
few | from 2 to 4, from 22 to 24 and so on |
many | 0, from 5 to 20, from 25 to 30 and so on |
other | for all other numbers |
# | is replaced by the value of the argument |
Substring replacement:
<span>
<Translator params={{where: "There", who: "are no cats"}}>
[where] [who]
</Translator>
</span>
Will render:
<span>
There are no cats
</span>
LocaleProvider
component provide React Context.
You can consume it for creating your own components.
where
registerCategory
- method for registering a new category.translate
- method for translating string. Return translated string.setLocale
- method for setting new current locale.availableLocales
- array, that contains available locales.currentLocale
- string, that matches to current locale.baseLocale
- string, that matches to base locale.
If you need translate string outside layout (for example in bootstrap file) or if you need raw string instead of Translator
component, use StorageTranslator
helper:
// pass base locale by second argument
const t = StorageTranslator(storage, "ru");
<meta content={t("Current year: [year]", "Meta", { year: (new Date()).getFullYear() })}/>
You can initialize storage object by yourself, but highly recommended use instantiated object:
const controlledStorage = new Storage({
initialLocale: "ru",
initialRecords: {
"en": {
"errors": {
"Неверный формат": "Wrong format"
}
}
}
});
// ...
<LocaleProvider storage={controlledStorage} {...LocaleProviderProps}>
// ...
</LocaleProvider>
// ...
const t = StorageTranslator(controlledStorage, "ru");
where
initialLocale
is the same asdefaultLocale
prop forLocaleProvider
.initialRecords
is the same ascommonTranslations
prop forLocaleProvider
.
So if you pass initial params to Storage
, you dont need to pass according props to LocaleProvider
.
You can also use react-router-dom to navigate on app with locale prefix in url:
<BrowserRouter>
<LangLink to="/index" {...NavLinkProps}>Home</LangLink>
</BrowserRouter>
Note: This component use react-router-dom context
where
NavLinkProps
- props of NavLink component
Will render if current locale is same as base locale:
<a href="/index">Home</a>
Will render if current locale is ua
:
<a href="/ua/index">Home</a>