Merge branch 'add-flatpak-locale-information' into 'master'

Add basic information about Locale runtime extensions

See merge request Librem5/developer.puri.sm!260

Apps/Packaging_Apps/Building_Flatpaks/Debugging.rst

@@ -46,11 +46,12 @@ application::
 
 This allows us to access debugging symbols in the sandbox.
 
+.. _building_flatpaks_debugging_shell:
+
 Running a Debug Shell
 ---------------------
 
-A debugging environment can
-be created by starting a shell inside the sandbox::
+A debugging environment can be created by starting a shell inside the sandbox::
 
    flatpak run --devel --command=bash sm.puri.Handy.Example
 

Apps/Packaging_Apps/Building_Flatpaks/Translations.rst

+.. _building_flatpaks_translations:
+
+Using and Testing Translations
+==============================
+
+.. contents::
+   :local:
+
+Applications that provide translations for different languages will be build with an additional ``.Local`` runtime extension that contains the files the application will use to display text in the user's language. As with :ref:`debug information <building_flatpaks_debugging>`, this cannot be exported as a binary bundle in the same way as for application flatpaks themselves, so we first need to find another way to install it.
+
+Installing the Locale Package
+-----------------------------
+
+In :ref:`building_flatpaks_installing_local`, we installed an application from
+a local repository by adding its repository to those registered with Flatpak on
+the system::
+
+   flatpak remote-add --no-gpg-verify my-local-repo myrepo
+
+Once this repository has been added with the ``my-local-repo`` remote, we can
+list its contents::
+
+   flatpak remote-ls my-local-repo -a
+
+The ``-a`` option ensures that the debug runtime extension is also listed. For
+the :ref:`examples_Files_Pictures` example, the above command produces this
+output::
+
+   Description                          Application                          Version          Branch
+   com.example.pictures                 com.example.pictures                                  master
+   com.example.pictures.Debug           com.example.pictures.Debug                            master
+   com.example.pictures.Locale          com.example.pictures.Locale                           master
+
+We install both the application and the locale runtime extension from the repository::
+
+   flatpak install my-local-repo com.example.pictures com.example.pictures.Locale
+
+We can now test the application using the locales for which we have translations available.
+
+.. TODO: It seems that you need to explicitly install the .Locale extension. Otherwise, the translations aren't installed properly.
+
+Testing Translations
+--------------------
+
+One way to test the translation of an application into a language is to run it from the command line, specifying the language to use with the ``LANGUAGE`` environment variable.
+
+For example, the :ref:`examples_Files_Pictures` example can be run in the following way::
+
+   LANGUAGE=nb flatpak run com.example.pictures
+
+The window title should be shown in Norwegian Bokmål instead of the default English.
+
+.. figure:: images/translated-pictures-app.png
+   :scale: 50%
+   :align: center
+   :alt: A screenshot of the translated Pictures application
+
+   A screenshot of the translated Pictures application
+
+If a ``.Locale`` extension is installed but the specified translation is not used by the application, it can be useful to :ref:`run a debug shell <building_flatpaks_debugging_shell>` inside the sandbox and check whether the relevant translation files are installed within.
+
+For example, we can inspect the translation files for the Pictures example by first starting the shell::
+
+   flatpak run --devel --command=bash com.example.pictures
+
+At the debug prompt, look for the translation files within the ``/app`` directory::
+
+   [📦 com.example.pictures ~]$ ls /app/share/locale/*
+   /app/share/locale/en_GB:
+   LC_MESSAGES
+   
+   /app/share/locale/nb:
+   LC_MESSAGES
+
+If either ``en_GB`` or ``nb`` are not directories then the translation files have not been installed properly.
+
+.. include:: /links.txt

Apps/Packaging_Apps/Building_Flatpaks/index.rst

@@ -16,4 +16,5 @@ cross-building applications for deployment on the Librem 5.
    Building
    Cross-Building
    Debugging
+   Translations
    Signing