i18n (internationalization) is the process of making an application work in different languages and cultures. This includes things like, translations of string resources through to to handling date formats as per the user’s language\/culture settings, along with things like decimal separators and more.<\/p>\n
There are several libraries available for helping with i18n coding but we’re going to focus on the react-i18next<\/a> in this post, for no other reason that it’s by other teams in the company I’m working for at the moment.<\/p>\n Getting Started<\/strong><\/p>\n The react-i18next<\/a> website is a really good place to get started and frankly I’m very likely to cover much the same code here, so their website should be your first port of call.<\/p>\n If you’re want to instead follow thought the process here then, let’s create a simple React app with TypeScript (as is my way) using<\/p>\n Now add the packages react-i18next<\/em> and i18next<\/em> i.e.<\/p>\n In this Getting Started<\/em> I’m going to also include the following libraries which will handle loading the translation files and more <\/p>\n Adding localized strings<\/strong><\/p>\n We’re going to first show an example of embeding the string into a .ts file, however it’s much more likely we’ll want them in a separate file (or multiple files). Let’s get this started by creating a file named i18n1.ts<\/em>.<\/p>\n In the file we’ll just write one string and here it is<\/p>\n As you can see we’re using the LanguageDetector to automatically set our resources. On my browser the language is set to en-GB so my expectation is to see the en<\/em> strings as I’ve not listed en-GB<\/em> specific strings.<\/p>\n IMPORTANT: Before we can use this, go to index.tsx<\/em> and import this file import “.\/i18n1”;<\/em> so the bundler includes it.<\/p>\n Display\/using our localized strings<\/strong><\/p>\n Now we’ll need to actually use our translation strings. react-i18next comes with hooks, HOC’s and standard JS type functions to interact with our translated strings. Let’s clear out most of the App.tsx and make it look like this<\/p>\n This code will simply display the English\/French buttons to allow us to change the language as we wish. Notice, however, that if we add a new language, such as de: { nativeName: “German”}<\/em> and no strings exist for that language, you’ll end up seeing the “key” for the string. We can solve this later.<\/p>\n At this point if all is working, you can start the application up and switch between the languages. You’ll see that the strings will be prefixed with code:<\/em> just to make it clear where the strings are coming from, i.e. our code file.<\/p>\n Moving to resource type files (part 1)<\/strong><\/p>\n As I mentioned, we probably don’t want to embed our string in code. It’s preferable to move them into their own .JSON files. <\/p>\n Create a folder within the src<\/em> folder named locales<\/em> (the names of the folders and files doesn’t really matter but it’s good to be consistent) and within that we’ll have one folder name en-GB<\/em> and another named fr<\/em>. So the English strings are specific to GB but the French covers all French languages locales.<\/p>\n Now in en-GB<\/em> create the file translations.json which will look like this<\/p>\n For the French translations, add translations.json to the fr<\/em> folder and it should look like this<\/p>\n Note the src: prefix is again, just there to allow us to see where our resources are coming from in this demo.<\/em><\/p>\n We now need to change our i18n.ts file to look like this<\/p>\n So in this code we’reimporting the JSON and then assigning to the resources<\/em> const. This is very similar to the other way we bought the resources into the i18n.ts file, just we’re importing via JSON files.<\/p>\n Moving to resource type files (part 2)<\/strong><\/p>\n There’s another way to import the translated strings and that is to simply include the files in the public folder of our React application. So in the public folder add the same folders and files, i.e. locales<\/em> folder with en-GB<\/em> and fr<\/em> folders with the same translation.json files as the last example. I’ve changed the src: prefix on the strings to public: again just so I can prove, for this demo, where the strings originate from.<\/p>\n In other words, here’s the en-GB<\/em> translations.json file<\/p>\n and the fr<\/em> translations.json file<\/p>\n Now back in our i18n.ts file change it to look like this<\/p>\n Fallback<\/strong><\/p>\n My browser is setup as English (United Kingdom)<\/em> which is en-GB<\/em> and all works well. But what happens if we add a detect a language where we have no translation strings for? Well let’s try it by adding a German option to the lngs<\/em> const in our App.tsx, so it looks like this<\/p>\n Now, what happens ? Well we’ve see the key for the string, which is probably not what we want in production, better to fall back to a known language. So we need to change the i18n.ts file and add a fallbackLng<\/em>, I’ll include the whole i18n object so it’s obvious<\/p>\n Now if our application encounters a locale it’s not setup for, it’ll default to the fallback language (in this case) English. We can also achieve this using<\/p>\n Finally with regards fallback languages, we can write code to determine the translation to use, again the Fallback documentation<\/a> has a good example of this, so I’d suggest checking that link out.<\/p>\n\r\nnpx create-react-app i18n-app --template typescript\r\n<\/pre>\n
\r\nnpm install react-i18next i18next --save\r\n<\/pre>\n
\r\nnpm install i18next-http-backend i18next-browser-languagedetector --save\r\n<\/pre>\n
\r\nimport i18n from "i18next";\r\nimport { initReactI18next } from "react-i18next";\r\nimport LanguageDetector from "i18next-browser-languagedetector";\r\n\r\ni18n\r\n .use(LanguageDetector)\r\n .use(initReactI18next)\r\n .init({\r\n resources: {\r\n en: {\r\n translation: {\r\n welcome: "code: Hello string en World"\r\n },\r\n },\r\n fr: {\r\n translation: {\r\n welcome: "code: Bonjour string fr World"\r\n }\r\n }\r\n },\r\n debug: true,\r\n interpolation: {\r\n escapeValue: false, \r\n },\r\n });\r\n\r\nexport default i18n;\r\n<\/pre>\n\r\nimport React from "react";\r\nimport ".\/App.css";\r\nimport { useTranslation } from "react-i18next";\r\n\r\nconst lngs: any = {\r\n en: { nativeName: "English"},\r\n fr: { nativeName: "French"},\r\n}\r\n\r\nfunction App() {\r\n const { t, i18n } = useTranslation();\r\n\r\n return (\r\n <div className="App">\r\n <div className="App-header">\r\n {t("welcome")}\r\n <div>\r\n {Object.keys(lngs).map(lng => {\r\n return <button key={lng} style={{margin: "3px"}}\r\n onClick={() => i18n.changeLanguage(lng)} disabled={i18n.resolvedLanguage === lng}>{lngs[lng].nativeName}<\/button>\r\n })}\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n );\r\n}\r\n\r\nexport default App;\r\n<\/pre>\n\r\n{\r\n "welcome": "src: Hello en-GB World"\r\n}\r\n<\/pre>\n\r\n{\r\n "welcome": "src: Bonjour fr World"\r\n}\r\n<\/pre>\n\r\nimport i18n from "i18next";\r\nimport { initReactI18next } from "react-i18next";\r\nimport LanguageDetector from "i18next-browser-languagedetector";\r\n\r\nimport enGB from "..\/src\/locales\/en-GB\/translation.json";\r\nimport fr from "..\/src\/locales\/fr\/translation.json";\r\n\r\nconst resources = {\r\n en: {\r\n translation: enGB\r\n },\r\n fr: {\r\n translation: fr\r\n }\r\n};\r\ni18n\r\n .use(LanguageDetector)\r\n .use(initReactI18next)\r\n .init({\r\n resources,\r\n debug: true,\r\n interpolation: {\r\n escapeValue: false, \r\n },\r\n });\r\n\r\nexport default i18n;\r\n<\/pre>\n\r\n{\r\n "welcome": "public: Hello en-GB World"\r\n}\r\n<\/pre>\n\r\n{\r\n "welcome": "public: Bonjour fr World"\r\n}\r\n<\/pre>\n\r\nimport i18n from "i18next";\r\nimport { initReactI18next } from "react-i18next";\r\nimport Backend from "i18next-http-backend";\r\nimport LanguageDetector from "i18next-browser-languagedetector";\r\n\r\ni18n\r\n .use(Backend)\r\n .use(LanguageDetector)\r\n .use(initReactI18next)\r\n .init({\r\n fallbackLng: {\r\n "en" : ["en-GB"]\r\n },\r\n debug: true,\r\n interpolation: {\r\n escapeValue: false, \r\n },\r\n });\r\n\r\nexport default i18n;\r\n<\/pre>\n\r\nconst lngs: any = {\r\n en: { nativeName: "English"},\r\n fr: { nativeName: "French"},\r\n de: { nativeName: "German"},\r\n}\r\n<\/pre>\n\r\ni18n\r\n .use(LanguageDetector)\r\n .use(initReactI18next)\r\n .init({\r\n resources,\r\n lng: "en-GB",\r\n fallbackLng: "en",\r\n debug: true,\r\n interpolation: {\r\n escapeValue: false, \r\n },\r\n });\r\n<\/pre>\n\r\nfallbackLng: {\r\n "default": ["en"]\r\n},\r\n\r\nUsing this syntax we can also map different languages to specific fallback languages, so for example we might map Swiss locale to map to use French or Italian. This is achieved by passing an array of fallback languages (as taken from the <a href="https:\/\/www.i18next.com\/principles\/fallback" rel="noopener" target="_blank">Fallback documentation<\/a>\r\n\r\n[code]\r\nfallbackLng: { \r\n "de-CH": ["fr", "it"], \/\/ French and Italian are also spoken in Switzerland\r\n},\r\n<\/pre>\n