i18n

Lightweight simple translation module for React apps based on gettext

Ussage

TranslateProvider

import { TranslateProvider } from '@cranium/i18n'
function APP () {
return (
<TranslateProvider
defaultLanguage="en"
storage={window.localStorage}
getTranslation={getTranslations}
>
<MyApp />
</TranslateProvider>
)
}

API

nametypedefault
defaultLanguageString'en'
langKeyString'lang'
translationsKeyString'translations'
storageObjectrequired
reloadFunction
useDefaultLanguageBooleanfalse
monoLanguageJSONBooleanfalse
getTranslationFunctionrequired
defaultTranslationsObject{}

defaultLanguage

Default language code that will be used when app opened at first time. You can check possible variants here

tip

You can use navigator.language

langKey

This is key that could be internally used by storage to cache user preferred language. For example if you are using localStorage Than it will be keyName in Storage.setItem

translationsKey

This is key that could be internally used by storage to cache remote translations. For example if you are using localStorage Than it will be keyName in Storage.setItem

storage(required)

Object that will cache data. In general you can use localStorage or AsyncStorage.

create own storage

class OwnStorage {
constructor(){
this.store = new Map()
}
getItem(key){
return this.store.get(key)
}
setItem(key, value){
this.store.set(key, value)
}
}

reload

Function that will be used when switching from rtl-ltr to reload page. Mostly it will be Location: reload() for Web apps. It is not required function and if you don't need to reload page on switching rtl-ltr, you can skip this option

useDefaultLanguage

Boolean flag to make Provider use default lang code instead of user selected. It could be use for example using Crowdin in app translations

import { TranslateProvider } from '@cranium/i18n'
function APP () {
return (
<TranslateProvider
defaultLanguage="ach"
storage={window.localStorage}
getTranslation={getTranslations}
useDefaultLanguage
>
<MyApp />
</TranslateProvider>
)
}

monoLanguageJSON

If getTranslation function return all languages at once than it should be true. Otherwise if getTranslation returns translation by each language separatelly, use false

defaultTranslations

Object with default translations pairs that will be used only on first load.

getTranslation

Function to load translations.

It could resolve all languages at once

function loadLanguages() {
return Promise.resolve({
en: {
'key': 'value'
},
uk: {
'key': 'value'
}
})
}

Or by language

function loadLanguages(lang: string) {
return Promise.resolve({
'key': 'value'
})
}

Please use i18n JSON format

{
"key": "value",
"keyDeep": {
"inner": "value"
},
"keyNesting": "reuse $t(keyDeep.inner)",
"keyInterpolate": "replace this {{value}}",
"keyInterpolateUnescaped": "replace this {{- value}}",
"keyInterpolateWithFormatting": "replace this {{value, format}}",
"keyContext_male": "the male variant",
"keyContext_female": "the female variant",
"keyPluralSimple_one": "the singular",
"keyPluralSimple_other": "the plural",
"keyPluralMultipleEgArabic_zero": "the plural form 0",
"keyPluralMultipleEgArabic_one": "the plural form 1",
"keyPluralMultipleEgArabic_two": "the plural form 2",
"keyPluralMultipleEgArabic_few": "the plural form 3",
"keyPluralMultipleEgArabic_many": "the plural form 4",
"keyPluralMultipleEgArabic_other": "the plural form 5",
"keyWithArrayValue": ["multipe", "things"],
"keyWithObjectValue": { "valueA": "return this with valueB", "valueB": "more text" }
}

gettext(message, data)

Returns the localized translation of message, based on the current language.

import { gettext } from '@cranium/i18n'
function Title(props){
return (
<>
<h1>{gettext("Hello")}</h1>
<h1>{gettext("Hello %(name)", { name: 'Alex' })}</h1>
</>
)
}

pgettext(message, domain, data)

Like gettext(), but looks the message up in the specified domain

import { pgettext } from '@cranium/i18n'
function Title(props){
return (
<>
<h1>{pgettext("Hello", "pageid")}</h1>
<h1>{pgettext("Hello %(name)", "pageid", { name: 'Alex' })}</h1>
</>
)
}

ngettext(singular, plural, n)

Like gettext(), but consider plural forms. If a translation is found, apply the plural formula to n, and return the resulting message. If no translation is found, return singular if n is 1; return plural otherwise.

import { ngettext } from '@cranium/i18n'
function Title(props){
return (
<>
<h1>{ngettext("Car", "Cars")}</h1>
<h1>{ngettext("%(count) Car", "%(count) Cars", { count: 1 })}</h1>
</>
)
}

npgettext( singular, plural, domain, n)

Like ngettext(), but look the message up in the specified domain.

import { npgettext } from '@cranium/i18n'
function Title(props){
return (
<>
<h1>{npgettext("Car", "Cars", "pageid")}</h1>
<h1>{npgettext("%(count) Car", "%(count) Cars", "pageid", { count: 1 })}</h1>
</>
)
}

useTranslations (hook)

Hook to use transtation in React component

import { useTranslations } from '@cranium/i18n'
function MyComponent(){
const { gettext, pgettext, ngettext, npgettext, setLanguage, language } = useTranslations()
retrun ...
}

Translator (render props)

React component to use tarnslations as Render prop

import { Translator } from '@cranium/i18n'
function MyComponent(){
retrun (
<Translator>
{({ gettext, pgettext, ngettext, npgettext, setLanguage, language })=>{
return <SomeJSX/>
}
</Translator>
)
}

useGetLanguage

Hook that return current language

import { useGetLanguage } from '@cranium/i18n'
function MyComponent(){
const lanf = useGetLanguage()
}

useSetLanguage

Hook that function to change language

import { useSetLanguage } from '@cranium/i18n'
function MyComponent(){
const setLanguage = useSetLanguage()
}

useGettext

Hook that returns gettetxt useGettetxt function

import { useGettext } from '@cranium/i18n'
function MyComponent(){
const gettext = useGettext()
}

usePGettext

Hook that returns pgettetxt usePGettetxt function

import { usePGettext } from '@cranium/i18n'
function MyComponent(){
const pgettext = usePGettext()
}

useNGettext

Hook that returns ngettetxt useNGettetxt function

import { useNGettext } from '@cranium/i18n'
function MyComponent(){
const ngettext = useNGettext()
}

useNPGettext

Hook that returns npgettetxt useNPGettetxt function

import { useNPGettext } from '@cranium/i18n'
function MyComponent(){
const npgettext = useNPGettext()
}
Edit this page