Add extras.xliff documentation

docs/Components/l10n.md

@@ -148,3 +148,55 @@ fr:1.0
 In this example, French has a score of 1.0, meaning that it is 100% translated. Spanish - Mexico has a score of about 0.83, indicating that around 83% of strings have been translated.
 
 The completeness score is used to determine if TS files for that locale should be generated.
+
+## Special Cases: server and language names
+
+Language name and server name strings are special cased in the Mozilla VPN localization pipeline.
+
+Although these strings are still translated by volunteers in Pontoon, they are declared on the `src/translations/extras.xliff` file and the process to add, remove and edit these strings is not the same as for any other string in the application.
+
+### Language names
+
+Language name strings are used in the languages chooser view of the application. This view shows both the language name translated in the currently active language and the native language name.
+
+#### Native language name translation
+
+In order to load the native language name translation without having to load the full `QTranslator` for each language whenever the language chooser menu is opened, the native language name translations are added to a map created at build time by the `generate_language_names_map.py` script. The resulting map contains a dictionary with the language code and the native language name translation:
+
+```cpp
+namespace LanguageStrings {
+const QMap<QString, QString> NATIVE_LANGUAGE_NAMES = {
+    {"sl", "slovenščina"},
+    {"sk", "slovenčina"},
+    {"pa_IN", "ਪੰਜਾਬੀ"},
+    {"pl", "Polski"},
+    ...
+```
+
+This map can be imported in C++ code through the header `i18nlanguagenames.h`.
+
+#### Adding, removing and editing language names
+
+##### Adding
+
+The `extras.xliff` file must always contain strings for all languages supported by the application. In order to know which languages are supported bythe application, one can simply look at the folder list in the i18n submodule. To guarantee the `extras.xliff` file and the suported language list is always up to date, a linter workflow is executed on each commit that checks if the i18n submodules and the `extras.xliff` language names are up to date.
+
+##### Removing
+
+The linter does not check if a language name string must be _removed_ from `extras.xliff`. When that is case, it is up to developers to do so adn the process is as simple as deleting the XML node that includes the unwanted string.
+
+##### Editing
+
+Just like strings in `strings.yaml` a string in `extras.xliff` should not be edited. If a language name base translation needs to be edited, it will need to be special cased in all scripts and a new XML node will need to be added to the `extras.xliff` file such e.g. `pt_BR2` in case the base translation for Brazilian Portuguese need to be changed.
+
+**It is best not to edit these base translations and only do so in when strictly required**.
+
+### Server names
+
+Server names are strings of country and city names where VPN servers are available. These strings are used in the server list view of the application. They are inherently dynamic, since servers may be added or removed from the server list at any time.
+
+In order to keep these strings up to date a CI Script it run at 7AM UTC every Monday to fetch the latest server list from Mullvad and update the `extras.xliff` file as needed -- this script can be found at `.github/workflows/i18n_server_list_update.yaml`. If everything is working, developers should not have to manually update server names in the `extras.xliff` file, they would only ever need to approve and merge these automatic pull requests.
+
+Just like the language names CI check, this script will never check for strings that need to be removed. It will only ever _add_ new strings and it is up to developers to remove strings when that is necessary.
+
+Editing these strings is inadvisable for the same reasons as language name strings.