DatafariUI i18n Configuration
Valid as of Datafari 5.4 when using DatafariUI
This page is meant to gather some tips for the development of the DatafariUI web app based on React.
i18n management
The library i18next is used to manage the translation key, translation file loading and management etc.
Basics
The “t” function is used to signify anything that must be translated and the argument of the function is used as the default display text if the key is not defined in the translation file. If a key is not translated in a language, English should be used as a default fallback.
The code of a simple component loading the t function and using it is displayed below:
import React from 'react';
import { useTranslation } from 'react-i18next';
const TestComponent = () => {
const { t } = useTranslation();
return (
<div>{t('Hello World')}</div>
)
};
export default TestComponent;Localization files
Locales files are located in the files public/locales/{localeid}/translation.json where {localeid} is the name of any locale (it, fr, en, …). Files look like this:
{
"AND": "",
"Add a search field": "",
"Advanced Search": "",
"All Content": "",
"All words": "",
"At least one word": "",
"Basic Search": "",
"Clear Filter": "",
"Click if you need to search in a specific field or want to combine with several fields or with basic search": "",
"Date": "",
"Delete Selected": "",
"Document content not indexed": "",
"Exact expression": "",
"Export Current Results": "",
"Extension": "",
"FILTERS": "",
"Favorite Document Path": "",
"Favorite Document Title": "",
"Feedbacks": "",
"Field": "",
"From": "",
"Go": "",
"Help": "",
"Language": "",
"Language selection": "",
"Manage Alerts": "",
"Manage Favorites": "",
"Manage Saved Queries": "",
"More Like This": "",
"My Favorites": "",
"Not these words": "",
"OR": "",
"Operator": "",
"Relevance": "",
"Results {{ start }} - {{ end }} of {{ total }}": "Resultats {{ start }} - {{ end }} de {{ total }}",
"Save Current Query": "",
"Save Query As Alert": "",
"Search Tools": "",
"Search for": "",
"Search in a specific field": "",
"Search tools": "",
"Select All": "",
"Show Less": "",
"Show More": "",
"Showing results for": "",
"To": "",
"Will NOT DISPLAY documents with AT LEAST ONE of these terms": "",
"Will search for ALL the terms listed": "",
"Will search for EXACTLY the sentence you entered": "",
"Will search for documents with AT LEAST ONE of these terms": "",
"anything": "",
"less than a month": "",
"less than a year": "",
"less than five years": ""
}On the left are the keys and on the right the translations. If any markup is present simply reproduce it without bothering about it, it represent some dynamic data that will be inserted at runtime. See one example below:
"Results {{ start }} - {{ end }} of {{ total }}": "Resultats {{ start }} - {{ end }} de {{ total }}",Automatic extraction of keys from code files
Thanks to the babel-plugin-i18next-extract plugin, it is possible to automatically extract the translation keys from the code. To do so, run the following command from the root folder of the project:
You will need access to the internet, or at least npm needs access to a repository with babel available. Indeed, npx relies on the package taken straight from repo instead of installing it locally. This is to ensure the latest version is used and reduce the clutter of dev dependencies installed locally.
Translating a new string
Let say we want to add the String “Welcome to Datafari” in the top menu of DatafariUI. We also want this String to be translated to French and German if those are the selected languages, else it should appear in English.
To do so, there are a few steps to follow:
Modify the top bar component to add the String calling the translation function
Adding the translations to the French and German localization files
Compiling DatafariUI
Modifying the top bar component
The top bar component is defined in src/Components/TopMenu/TopMenu.js.
Within the return statement (which returns the definition of what will be displayed in JSX) we need to add our String where we want it to appear.
Within the Toolbar element, after the NavLink containing the logo, there is a div currently displaying Datafari. We will change that.
It looks like:
See line 13 of this snippet the “Datafari” String, we will change that to “Welcome to Datafari”. But as we want it to be translated when the user changes the language setting, we need to use the translation function t.
This function is already imported in this component as it is used is other places, so no need to worry about that here. If it is not imported in the component you want to modify, refer to the example above to see how to import it.
After modification, the snippet looks like the following:
The value you put as an argument to the translation function is used as a key in the localization files.
If no translation is available for this key in either your chosen language localization file or the English localization file, then the String used as an argument is what will be displayed.
Order of resolution given I have chosen French as my language in the UI: French translation → English Translation → function argument
The first that exist is used.
Adding the translations to the localization files
The function argument is the English version of the text, so adding a translation to the English localization file is not necessary. However, it is still a good habit to create it. We will also add the French and German translations.
Localization files are named translation.json and are located in the folders public/locales/{localid}.
For our needs, we will modify public/locales/en/translation.json, public/locales/fr/translation.json and public/locales/de/translation.json.
I show below only snippet of the files with the added key “Welcome to Datafari”:
en
fr
de
Building the project and deploying
You can then build DatafariUI (https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/1502773249 ) and deploy it with the new translated String.
Modifying a translated String in a deployed DatafariUI instance
If String already translated in DatafariUI end up being wrong for some reason, it is possible to correct them without rebuilding and deploying DatafariUI all over again.
To do so, you can access the translations file in the {DATAFARIUI_ROOT}/locales directory and modify the incorrect strings there.
The next time clients will load the interface, they will see the new translations.
For example, lets say I have a default installation of DatafariUI with my Datafari and I want the french translation for “Welcome to Datafari” to be “Bienvenue sur Datafari” because there was typo in the previous tutorial !
I can go ahead and modify the file /opt/datafari/www/locales/fr/translations.json and make it look like:
This will correct the typo for anyone accessing my instance of DatafariUI (letting the dev team know so that they can correct in the code would be great too !)