Introduction. How it works
In this article, I'll describe the process and possible areas of translation in Django. The process of translating HTML files and Python scripts is very different from, say, translating JS files.
When localizing, you also need to understand how exactly you want to display a different language version. A good idea is to display this directly in the URL. There are several options:
- Create a separate website with a corresponding domain. Like example.de. This is too expensive and impractical.
- Add a subdomain. Like ru.example.com
- Add a directory. Like example.com/en/
- Or use the URL parameter example.com?loc=en
Each of these options has its pros and cons. And I'm not the one in the right place to talk about them. Everything is described in detail here on Google's blog. I've only tried the directory option because... well, I have a single server and a limited budget. Therefore, in this article, you'll find this method of displaying translations. In any case, translating a Django website can be divided into four tasks: translating strings in Python code, translating Django models, translating strings in templates, and translating strings in JavaScript code.
The process itself can be divided into the following stages:
- Marking all the strings to translate
- Collecting all the marked strings
- Filling up the translations strings
- Compilation of a special *.mo files
But before you start translating, you need to fine-tune your website. There's no other way.
Basic setup
First, let's enable the appropriate middleware. Its main role is to redirect to the appropriate localized pages and insert the translation strings needed for the site's current locale.
In the settings.py file:
You also need to record the default language code, which is also the current language, and prepare a list of supported localizations (translations) for the site. Also, add the USE_I18N global variable. This last point is optional; it's enabled by default, but I just like to have everything explicitly configured.
The final step is specifying the localizable routes. In this case, it doesn't make sense to localize all the api or admin paths, and especially not the allauth paths. These are the ones that will remain untouched. In other words, we'll localize our frontend. These are the about, contacts, homepage, email confirmation, and password reset pages.
Add the following lines to the urls.py file:
By the way, the i18n_patterns function can only be used in the main urls.py file. That's it.
Preliminary setup is complete.
Website Localization Step by Step
All subsequent subchapters will describe the website localization process, from collecting strings for translation to compiling them.
Selecting Strings for Translation
We need to specify what actually needs to be translated, and for each part of the website, be it a template, Python code, or JavaScript code, this will be different.
Translations in Python Code
To mark strings for translation, you need to import the following functions: gettext and gettext_lazy.
Next, you simply need to wrap the string you need in gettext or gettext_lazy. Note that not every string can be wrapped in a gettext function. For example, variables or calculated values. For example:
In this example, Django will only detect the first string, "Usual string." It will ignore all the others.
I also imported the gettext_lazy function. What's special about it, and when should I use it? Generally speaking, the only difference between the two is that the latter takes a string from the *.po file only when that string is used on the server. At least that's what the official Django website says.
This function (gettext_lazy) is worth using when translating Django models and their attributes, as well as descriptions for the admin panel. But in 90% of cases, gettext will suffice. Plus, as I noted earlier, making models international requires more than Django's built-in utilities.
Translations in Templates
To translate text in templates, you only need to know three tags:
At the beginning of your template, you'll need to load a special module, i18n. Every time you need to translate text in your template, load the module, even if this template inherits from another template that already has i18n loaded.
After the i18n module has been loaded, you have two options:
- The first is to use single-line translation.
- The second is to use multi-line translation.
The difference between them is that in the second case, everything between the tags will be translated, including other tags. Stay tuned.
Translations in JS files
Setting up JavaScript code translations is probably the most difficult and tedious part. Although at first glance, it seems like there's a tutorial and nothing out of the ordinary is required. But more on that later. Let me first show you how to set up JS translations via Django.
The first thing you need to do is include the appropriate paths in urls.py. Moreover, I would like to point out that if you use the i18n_patterns function, you need to include the JavaScriptCatalog class there.
The JavaScriptCatalog class will generate a mini-JS library for us with a catalog of translation strings. Yes, this will slow down page loading speed somewhat, so we'll need to remember to cache it in the future. Now let's include this script.
The translation backend is now configured. Now we need to mark the strings we want to translate. So, we only need the gettext() function, which is defined in the JS file we included earlier. For example, like this:
This is how we mark strings for translation. We simply wrap them in the appropriate gettext function.
Collecting Strings
After setting up translations for templates, Python, and JavaScript, we need to collect all marked strings into *.po files. First, create a locale directory in each application that contains strings for translation. If all the necessary directories (locale) for translation have been created, run the following command:
If you marked lines in JS, you need to run another command to collect lines from JS files. In this command, we use the -d flag with the value djangojs.
Please also use the -i or --ignore flag. Look, I'm using Node.js and ReactJS. They're all in the node_modules directory, and there are actually more. If you don't use this flag, Django will reliably check every JS file in your project, and there will be tens of thousands of them.
Translations, how to fill them in
These two commands will result in the files django.po from the first command and djangojs.po from the second command. They will contain lines like this, for example:
You'll need to fill in everything in the "" after the msgstr. Don't touch anything inside the msgid, that's the first thing. And second, when translating multi-line elements (those starting with "\n") after the msgid, the msgstr must also start with "\n."
In any case, if there are any errors during compilation, they're very informative, and you won't have any problems fixing them yourself. Speaking of compilation,
Compiling Translations
The final step in translating is compiling them into *.mo files. To compile translations, regardless of whether they're templates, Python, or JS code, use the following command:
Congratulations! We've finished translating our website, and it can now support many other languages, regardless of which strings are located or where. However, if you're not satisfied with the quality of your JS file translations, or if you're having trouble translating your React JS files—it simply can't find them—then continue reading the next chapter about translating JS strings using the i18next React module.
Translating JS files using the i18next framework
Unlike translating JS files using Django, setting up React for this is much more complicated. But it guarantees that all the necessary strings will be found. Let's install the necessary packages first:
Let's take a look at each package we installed:
- i18next - the core functionality for translations
- react-i18next - the link between React and i18next
- i18next-browser-languagedetector - allows you to detect the user's current browser language and change it
- i18next-http-backend - delivers translations to the end client
- i18next-parser - collects all the strings for translation
Now all this needs to be configured. Let's start with the parser. Create a file called i18next-parser.config.js in the Frontend directory, which is where your node_modules directory is. Then paste the following content.
Compared to the original, I changed a lot.
- First, I changed the lexer, lexers:, for JS files.
- Second, I added locales, locales:, for English, Russian, German, Spanish, and French.
- Third, I changed the output path. I'm placing all translation files in the static directory. Why? When I host this site on the server, all static files will need to be served by that server. Accordingly, all these files will need to be moved to another location. And Django already has a built-in command for copying all static files to this location—collectstatic. That's right, including our localizations.
- Fourth, I set all separator values to false. I did this because I don't use their translation functions, as demonstrated in their tutorial. I wrap strings and sentences in the appropriate translation function, rather than creating specific keys for each case.
The next thing we need to do is create an i18n.js file next to index.js and insert the following content:
In this file, we configure the i18n module. We define how we'll deliver static files to the end user (the Backend module) and how we'll detect the user's language (the LanguageDetector module). In the latter case, it's important to specify that 'path' comes first, as this is how we specify the language change.
We import this component:
Now, using one of the components as an example, I'll show you how to mark strings that need to be translated. First, import the translation function:
Next, in the component function, we use the hook:
And now, to wrap the necessary string for translation:
As you may have noticed, I'm passing the t function further as an argument to the onConfirmEmail handler. I did this because translations are needed not only in React components but also in regular handlers and functions. I couldn't find another way to globally define a translation function, so in each function that needs translation, I define an additional parameter—the t translation handlers.
Let's collect all the strings I've highlighted into translation files. This is why we installed the i18n-parser module. And to make future development of our website easier, we'll write a separate script for performing translations in package.json.
You only need to specify where and what to search using a special pattern. ** means search all folders and subfolders. *.js means search any files with the .js extension.
Let's run the script, and it will find all the strings for translation and create all the previously specified localization files.
You'll find all the translation files at static/locales/LOCALE/translation.json. Here's an example of a generated localization file for Russian:
Next, let's look at the console output and what the page looks like when translated into German.
Using one of my sites as an example.
As you can see from the console, we made two XMLHttpRequest (or XHR) requests to get German and English localizations. Why two and not one? That's because we specified fallbackLng: 'en' in i18n.js. This means if German localization isn't available, we'll use the default locale.
You can also see how the LanguageDetector module triggered and detected the user's language change. That's it, the translations of the JS code to React are complete.
Epilogue
In this article, we've covered all the possible cases where translations might be needed. Translations in templates or Python code aren't difficult.
While setting up and creating translations for JS code is also easy, keep in mind that it works well with vanilla JS. Other translations can present some challenges. For example, proper translations of React code require installing additional packages.
Finally, I'd like to add that translation isn't a simple matter and takes a long time. And I hope I was able to make your work with them at least a little easier.
