Talkr is the lightest i18n provider for React applications. It supports Typescript, provides autocompletion, has 0 dependencies, and is very easy to use.
// with npm
npm install talkr
// with yarn
yarn add talkr
__dynamicValue__
.count
parameter to Talkr's translation function. Talkr will then chose the right word or sentence between zero
, one
, two
, few
and many
.🤓: Some languages have more complex plural rules, that may require these five options to offer a perfect user experience. For instance, Arabic handle
zero
,one
,two
,numbers between 3 and 10
andnumbers over 10
as separate entities. If a language doesn't need all these subtleties - like english - you can only writezero
,one
andmany
in the JSON file.
{
"hello": "hello",
"feedback": {
"error": "The connection failed",
"success": "The connection succedeed"
},
"user": {
"describe": {
"simple": "You are __name__",
"complex": "You are __name__ and you like __hobby__"
}
},
"idiom": {
"sovereign": {
"female": "Long live the Queen!",
"male": "Long live the King!"
}
},
"message-count": {
"zero": "you don't have new messages",
"one": "you have 1 message",
"many": "you have __count__ messages"
},
"days": ["Monday", "Tuesday", "Wednesday"],
}
Provider
languages
and your defaultLanguage
.detectBrowserLanguage
(see [props](#Available props)).import * as React from "react";
import { createRoot } from "react-dom/client";
import { Talkr } from "talkr";
import App from "./app";
import en from "./i18n/en.json";
import fr from "./i18n/fr.json";
const root = createRoot(document.getElementById("root"));
root.render(
<Talkr languages={{ en, fr }} defaultLanguage="en">
<App />
</Talkr>,
);
useT
.T
from useT
.
between each key. Based on the JSON example above, we could print the sentence The connection succedeed
by simply writing T("feedback.success")
import React from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
return (
<>
<h1>{T("hello")}</h1>
<div>{T("feedback.success")}</div>
</>
);
}
__dynamicValue__
)"user": {
"describe": {
"simple": "You are __name__",
"complex": "You are __name__ and you like __hobby__"
}
}
import React from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
return (
<>
<h1>{T("user.describe.complex", { name: "joe", hobby: "coding" })}</h1>
</>
);
}
count
property to the objectzero
, one
and many
values to your JSON files."message-count": {
"zero": "you don't have new messages",
"one": "you have 1 message",
"many": "you have __count__ messages"
}
import React, { useState } from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
const [count, setCount] = useState(0);
return (
<>
<h1>{T("message-count", { count })}</h1>
<button onClick={() => setCount(count + 1)}>+1</button>
</>
);
}
gender: m
for male
, or gender: f
for female
.male
and female
values to your JSON files."idiom": {
"sovereign": {
"female": "Long live the Queen!",
"male": "Long live the King!"
}
}
import React from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
return (
<>
<h1>{T("idiom.sovereign", { gender: "m" })}</h1>
</>
);
}
listType?: "conjunction" | "disjunction"; // ""conjunction" by default
listStyle?: "long" | "narrow"; // "narrow" by default
"days": ["Monday", "Tuesday", "Wednesday"],
import React from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
return (
<>
<h1>{T("days", { listType: "conjunction" })}</h1>
</>
);
}
useT()
defaultLanguage
sent to the provider.import React, { useState } from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T, setLocale, locale } = useT();
return (
<>
<h1>{T("hello")}</h1>
<p>{locale}</p>
<button onClick={() => setLocale("fr")}>speak french</button>
</>
);
}
Autocompletion for translation keys is available in Typescript projects. Because json must be parsed at compile time, you will need to create your own useAutocompleteT
hook with Talkr's Autocomplete
type wrapper.
Here's how to do it:
Typescript >=4.5.5
(we don't guarantee it will work on older versions)translate.tsx
file anywhere in your app(translate.tsx
can be named as you want)en.json
)Autocomplete
useAutocompleteT
hook around Talkr's useT()
import { useT, Autocomplete, TParams, tr } from "talkr";
import en from "./en.json";
type Key = Autocomplete<typeof en>;
export const useAutocompleteT = () => {
const { locale, languages, defaultLanguage } = useT();
return {
T: (key: Key, params?: TParams) =>
tr({ locale, languages, defaultLanguage }, key, params),
};
};
If you prefer to keep the useT
naming, just write:
import { useT as useTr, Autocomplete, TParams, tr } from "talkr";
import en from "./en.json";
type Key = Autocomplete<typeof en>;
export const useT = () => {
const { locale, languages, defaultLanguage } = useTr();
return {
T: (key: Key, params?: TParams) =>
tr({ locale, languages, defaultLanguage }, key, params),
};
};
You now have the choice between using your own useAutocompleteT
hook - which provides real-time autocompletion - or using Talkr's useT
- which doesn't provide autocompletion - in your app.
import { useAutocompleteT } from "./translate";
function App() {
const { T } = useAutocompleteT();
return (
<>
<h1>{T("feedback.success")}</h1>
<h4>{T("user.describe.complex", { name: "joe", hobby: "coding" })}</h4>
</>
);
}
🤓 Pro-tip: since you will need to import
useAutocompleteT
fromtranslate.tsx
, it is highly recommended to add an aliastranslate
to your builder's config andtsconfig.json
.
This will allow you to write
import { useAutocompleteT } from "translate" 👍
instead of
import { useAutocompleteT } from "../../translate" 👎
Exemples: webpack
resolve: { extensions: [".ts", ".tsx", ".js", "jsx", ".json"], alias: { translate: path.resolve(__dirname, "src/translate/"), }
tsconfig
{ "compilerOptions": { "paths": { "translate/*": ["src/translate/*"] } }}
for other bundlers, please refer to their respective documentations.
import { StyleSheet, Text, View } from "react-native";
import { Talkr } from "talkr";
import en from "./src/i18n/en.json";
import fr from "./src/i18n/fr.json";
import MyComponent from "./src/MyComponent";
export default function App() {
return (
<Talkr languages={{ en, fr }} defaultLanguage="en">
<View style={styles.container}>
<MyComponent />
</View>
</Talkr>
);
}
div
, h1
, etc.) by Text
.Intl
api is not available in React Native, the count
param will only return three types of plural keys: zero
, one
and many
. Please adjust your json files accordingly.import React, { Text, Button } from "react-native";
import { useState } from "react";
import { useT } from "talkr";
export default function MyComponent() {
const { T } = useT();
const [count, setCount] = useState(0);
return (
<>
<Text>{T("hello")}</Text>
<Text>
{T("user.describe.complex", { name: "joe", hobby: "coding" })}
</Text>
<Text>{T("message-count", { count })}</Text>
<Button onPress={() => setCount(count + 1)} title="+1" />
</>
);
}
You can pass these props to Talkr's provider | Type | Role | |
---|---|---|---|
languages | object |
object containing all your json files. Typical format: {en: {...}, fr: {...}} |
|
defaultLanguage | string |
default language of your app (a similar key must be included in the language prop) |
|
detectBrowserLanguage | boolean |
if true , Talkr will automatically use browser language and override the defaultLanguage . If the browser language is not included in your available translations, it will switch back to defaultLanguage . Not available in React Native. Use expo-localization to fetch the default user locale instead. |
🤓: The auto-detect language feature will always return a simple key such as 'fr' instead of 'fr_FR'. Keep things simple and always declare your languages with 2 letters.
DoneDeal0
If you or your company uses Talkr, please show your support by becoming a sponsor! Your name and company logo will be displayed on the README.md
.
https://github.com/sponsors/DoneDeal0
Also see our website