This guide includes instructions on:
Setting up the technical infrastructure to support multi-language in the LiteFarm application
Adding the file structure to add a new language or dialect to the application
Updating the actual dictionary for a new language or dialect
The first two sections should be carried out by an engineer, while the third can be carried out by a user that is familiar with the use of Github. You’ll need a Github account to carry out any of these operations.
To setup infrastructure we followed the guide by React-i18Next, following these steps
Install i18next and react-18next using the command
npm install react-i18next i18next i18next-parser --save |
i18next-parser will allow a user to scan for new translations in any part of the webapp, using either the useTranslation hook or the withTranslation Higher Order Component. For example, if I have a t('KEY_A') which is not located in the lang/en/translation.json running npm run i18n will create a new entry in the translation.json.
Create the base configuration file needed to run the parser script taking this as base template, the only modifications done were changing the defaultValue (which is the value that the parser will use for any translation not found) to “MISSING” and adding locales for en, es, pt and fr.
Run in webapp npm run i18n
Insert withTranslation HOC and useTranslation hooks in every component in the app.
TAG every Label, or visible text in the app with an appropiate key. Try to separate the views in different objects of the translation For example, if working on a login component wrap every translation for the Login in a “LOGIN” object, you can find various examples of this practice in the current translation.json.
Re-run npm run i18n and checkout the lang/en/translation.json which will have all tags that were added.
Translate those tags within the translation file.
Adding a new language or dialect after the initial configuration was done should be a simple process.
Include the new language locale (using the first 2 letters of it) in the locales array located in the i18next-parser.config.js which looks like this. In the case of a dialect, please concatenate the language and the locality, for example ‘pt-br’ for Portuguese Brazil.
locales: ['en', 'es', 'pt', 'fr'] |
Run npm run i18n which should create a new folder with 2 files lang/[your_locale]/translation.json and lang/[your_locale]/common.json.
Modify the lang/i18n.js file, to include the new locale in the app.
Import both files in the beginning on the file doing
import [your_locale] from './[your_locale]/translation.json'; import [your_locale]_common from './[your_locale]/common.json'; |
Include the new locale in the resources object, like so:
fr:{
translation: fr,
common: fr_common
}, //INCLUDE THE CODE BELOW
[your_locale]:{
translation: [your_locale],
common: [your_locale]_common
} |
After that you can proceed to translate the files that were created and making a PR on our repo as described in the next section
Navigate to the LiteFarm repo at https://github.com/LiteFarmOrg/LiteFarm
Make a new branch from the develop branch (see image) naming it whatever is easy to remember, in this case I’ve chosen “my-translation-branch”
3. Type the following URL into your browser, substituting the name of your branch where it says “my-translation-branch”: https://github.com/LiteFarmOrg/LiteFarm/tree/my-translation-branch/packages/webapp/src/lang
You should see something like the following:
4. Click into the folder that corresponds to the language you’re translating, for example, “pt” for “Portuguese”. You should now see something like this:
5. Click into whichever file you’d like to work on. For our example, I’ll select the first - “common.json”
6. Click the “pencil” icon at the top right. You should now see something like this:
7. Translate all, or as many terms as you have time for, in the second column (notice ‘desculpa’ in the last row as an example). If you have any questions or need more context, feel free to reach out to our team at support@litefarm.org. When you’re done, scroll down to the bottom of the screen where it says “Commit changes”
8. Write a brief note that will help you remember what you did and then click “Commit changes”. For short files such as common.json you’ll probably only need to do one commit per document. For larger documents, such as crops.json it may take several commits to finish. Once done, go to the link in #5 and proceed to the next file.
9. Once you’ve finished with all your desired changes, make a pull request describing your updates. The LiteFarm team will review your PR and either merge it in or come back to you with any questions or suggestions.