Update the i18n documentation (#743)

* Update the i18n documentation
* Update doc/i18n.md
Co-authored-by: Martin Vidner <mvidner@suse.cz>

doc/i18n.md

@@ -27,6 +27,9 @@
     - [Building POT File](#building-pot-file)
     - [Cockpit Details](#cockpit-details)
     - [Development Server](#development-server)
+    - [D-Bus Backend](#d-bus-backend)
+      - [Backend Translations](#backend-translations)
+  - [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -448,3 +451,71 @@ checks the language cookie and uses HTTP redirection to load the respective
 language file. It uses redirection because the built translation files are only
 available in the webpack memory. But the result is the same, the browser gets
 a different content according to the currently configured language.
+
+### D-Bus Backend
+
+The D-Bus service backend implements a writable `UILocale` property which
+defines the locale used by the service.
+
+For debugging purposes you can get the current value or set a new one using
+command line:
+
+```shell
+# get the current locale
+busctl --address=unix:path=/run/agama/bus get-property org.opensuse.Agama1 /org/opensuse/Agama1/Locale  org.opensuse.Agama1.Locale UILocale
+# set a new locale
+busctl --address=unix:path=/run/agama/bus set-property org.opensuse.Agama1 /org/opensuse/Agama1/Locale  org.opensuse.Agama1.Locale UILocale s cs_CZ
+```
+
+The `UILocale` property is a single global value shared by all connected clients.
+That means it is possible to use only one language for all clients, if
+more users connect to the server and uses a different UI language then there
+will be race conditions and the other users might see the texts coming from the
+backend in another language than expected.
+
+This is a known limitation, we expect that only one user at a time will access
+the Agama installer or if multiple users use the same server we expect that
+they will be from the same team or company using the same language.
+
+#### Backend Translations
+
+The backend might return texts from external components like `libstorage-ng`.
+Make sure the translations for those components are also available for Agama,
+e.g. the `libstorage-ng` translations are stored in the `libstorage-ng-lang`
+package or the YaST translations are stored in `yast2-trans-<LANG>` packages.
+
+## Troubleshooting
+
+Here are some hints what to do when some untranslated text appears in the Agama
+UI.
+
+1. Check that the text is marked for translation, for a quick verification
+   you might try setting the [testing language](#testing-language)
+2. If the text comes from backend or the other parts check that the appropriate
+   [language package](#backend-translations) is installed
+3. The text should be [extracted into the POT file](#building-pot-file)
+4. The [agama.pot](
+   https://github.com/openSUSE/agama-weblate/blob/master/web/agama.pot) in the
+   `agama-weblate` repository is up to date, if not then run the [Weblate Update
+   POT](https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml)
+   Github Action manually
+5. The text is translated in the [Weblate repository](
+   https://l10n.opensuse.org/projects/agama/)
+6. The translation is included in the respective PO file in the [agama-weblate](
+   https://github.com/openSUSE/agama-weblate) repository
+7. The PO file in the [agama](
+   https://github.com/openSUSE/agama/tree/master/web/po) repository is up to
+   date, if not the check whether there is an [open pull request](
+   https://github.com/openSUSE/agama/pulls?q=is%3Aopen+is%3Apr+label%3Atranslations+label%3Abot)
+   with the change, if yes then check it and merge, if not then run the [Weblate
+   Merge PO](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-po.yml)
+   GitHub Action manually, then check the created pull request
+8. The translated string should be present in the built packages, run
+   `npm build` command and check the `dist/po.*.js` files, check the built RPM
+   package
+9. The translations are loaded by the browser, check the content loaded for the
+   `po.js` file
+10. Check the current language used in the browser, run `cockpit.language`
+    command in the development tools console, check the `CockpitLang` cookie
+    value (run `document.cookie` command in the console)
+11. Check the language used by the [service backend](#d-bus-backend)