[i18n] Add a French translation.

doc/index.rst

@@ -1824,3 +1824,60 @@ the trace output) to a region of memory:
 
 All the other semihosting calls require no special handling, because
 they only *read* the memory of the Arm CPU, rather than writing it.
+
+Translations
+============
+
+The Arm Tarmac Trace Utilities rely on GNU's ``gettext`` to provide
+internationalization.
+
+Adding a translation
+--------------------
+
+A new translation can be easily added. Let's walk this thru an example,
+adding the French translation ``fr_FR``. This assumes that you have
+``gettext`` available on your machine. 
+
+.. code-block:: bash
+
+  $ mkdir po/fr_FR
+  $ msginit -l fr_FR -i po/tarmac-trace-utilities.pot -o po/fr_FR/tarmac-trace-utilities.po
+
+We then need to add our new translation to the infrastructure.
+Edit file ``po/CMakeLists.txt`` to add our new translation to
+the list of directories to consider and copy a boilerplate
+``CMakeLists.txt`` into the ``fr_FR`` translation dir.
+
+.. code-block:: bash
+
+  $ vim po/CMakeLists.txt
+  ... edit ...
+  $ cat po/CMakeLists.txt
+  ...
+  add_subdirectory(fr_FR)
+  ...
+  $ cp po/en_GB@wide/CMakeLists.txt po/fr_FR/
+
+Et voila ! The infrastructure is now in place, you only need to use your
+favorite text editor to translate all strings from
+``po/fr_FR/tarmac-trace-utilities.po``.
+
+In case you want to test the translation, the easiest is to install the tarmac trace
+utilities as some additional (and required !) steps are performed only at installation. In
+order not to pollute your system, you can set the cmake installation prefix with 
+``-DCMAKE_INSTALL_PREFIX:PATH=/some/where``.
+
+The translation can then be locally tested by setting the ``LANGUAGE`` environment variable.
+
+.. code-block:: bash
+
+  $ cmake -G Ninja -DCMAKE_INSTALL_PREFIX:PATH=/some/where ...
+  $ ninja
+  $ ninja instal
+  $ LANGUAGE=fr_FR /some/where/bin/tarmac-vcd --help
+  usage: tarmac-vcd [options] FICHIERTRACE
+  options:
+      --image=FICHIERIMAGE   nom du fichier contenant l'image
+      --load-offset=DECALAGE
+                             décalage des addresses dans l'image par rapport à
+                             celles de la trace

po/CMakeLists.txt

@@ -1,5 +1,32 @@
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
+
+function(add_this_po lang)
+  gettext_process_po_files(${lang} ALL
+    PO_FILES ${CMAKE_CURRENT_SOURCE_DIR}/tarmac-trace-utilities.po
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LOCALEDIR})
+
+  set(mo_files
+    ${mo_files} ${CMAKE_CURRENT_BINARY_DIR}/tarmac-trace-utilities.gmo
+    PARENT_SCOPE)
+endfunction()
+
 add_subdirectory(en_GB@wide)
 add_subdirectory(en_GB@rot13)
+add_subdirectory(fr_FR)
 
 if(CMAKE_SYSTEM_NAME MATCHES "Windows" AND Python3_FOUND)
   add_custom_command(OUTPUT translation.rc

po/en_GB@rot13/CMakeLists.txt

@@ -1,7 +1,18 @@
-gettext_process_po_files(en_GB@rot13 ALL
-  PO_FILES ${CMAKE_CURRENT_SOURCE_DIR}/tarmac-trace-utilities.po
-  INSTALL_DESTINATION ${CMAKE_INSTALL_LOCALEDIR})
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
 
-set(mo_files
-  ${mo_files} ${CMAKE_CURRENT_BINARY_DIR}/tarmac-trace-utilities.gmo
-  PARENT_SCOPE)
+get_filename_component(_lang ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+add_this_po(${_lang})

po/en_GB@wide/CMakeLists.txt

@@ -1,7 +1,18 @@
-gettext_process_po_files(en_GB@wide ALL
-  PO_FILES ${CMAKE_CURRENT_SOURCE_DIR}/tarmac-trace-utilities.po
-  INSTALL_DESTINATION ${CMAKE_INSTALL_LOCALEDIR})
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
 
-set(mo_files
-  ${mo_files} ${CMAKE_CURRENT_BINARY_DIR}/tarmac-trace-utilities.gmo
-  PARENT_SCOPE)
+get_filename_component(_lang ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+add_this_po(${_lang})

po/fr_FR/CMakeLists.txt

@@ -0,0 +1,18 @@
+# Copyright 2024 Arm Limited. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is part of Tarmac Trace Utilities
+
+get_filename_component(_lang ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+add_this_po(${_lang})