Talkr is a super small i18n provider for React applications. It supports Typescript, has 0 dependencies, and is very easy to use.

• auto-detect browser language
• auto-detect plural rules based on any language
• dynamic translations with multiple keys
• access deeply nested keys in json translations files

• Create your JSON translation files.
• Surround dynamic values by double underscores: __dynamicValue__.
• To allow automatic plural detection, you will need to pass a 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 and numbers over 10 as separate entities. If a language doesn't need all these subtleties - like english - you can only write zero, one and many 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__"
    },
  },
  "message-count": {
    "zero": "you don't have new messages",
    "one": "you have 1 message",
    "many": "you have __count__ messages"
  }
}

• In your index file, import your JSON translations
• Wrap your App with Talkr Provider
• Pass it your available languages and your defaultLanguage.
• You also have the option to let Talkr detect browser's language with the prop detectBrowserLanguage (see #Props).

import * as React from "react";
import ReactDOM from "react-dom";
import { Talkr } from "talkr";
import App from "./app";
import en from "./i18n/en.json";
import fr from "./i18n/fr.json";

ReactDOM.render(
  <Talkr languages={{ en, fr }} defaultLanguage="en">
    <App />
  </Talkr>,
  document.getElementById("root")
);

• In any component, import Talker's translation function t.
• Fetch the desired sentence as if you were directly accessing an object, by adding . 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 { t } from "talkr";

export default function MyComponent() {
return (
  <>
  <h1>{t("hello")}</h1>
	<div>{t("feedback.success")}</div>
  </>
);
}

• To handle dynamic translations, just add an object with all necessary dynamic values
• To make it work, you need to surround the dynamic values by double underscores in your JSON files (__dynamicValue__)

import React from "react";
import { t } from "talkr";

export default function MyComponent() {
return (
  <>
  <h1>{t("user.describe.complex", {name:"joe", hobby: "coding"})}</h1>
  </>
);
}

• To handle plural, just add a count property to the object
• To make it work, you need to provide both zero, one and many values to your JSON files.

import React, {useState} from "react";
import { t } from "talkr";

export default function MyComponent() {
const [count, setCount] = useState(0)
return (
  <>
	<h1>{t("message-count", {count})}</h1>
	<button onClick={()=> setCount(count + 1)}>+1</button>
  </>
);
}

• Access and update the locale by using the hook useLocale()
• If the provided locale doesn't match any JSON translation files, Talkr will use the defaultLanguage sent to the provider.

import React, {useState} from "react";
import { t, useLocale } from "talkr";

export default function MyComponent() {
const {setLocale, locale} = useLocale()
return (
  <>
	<h1>{t("hello")}</h1>
	<p>{locale}</p>
	<button onClick={()=> setLocale("fr")}>speak french</button>
  </>
);
}

You can pass these props to Talkr's provider

🤓: 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.

You can access these props from Talkr's hook useLocale()

DoneDeal0

Mouth logo made by emilegraphics from the Noun Project