From 329d190fbf0464c7ceef2d2a89d4e9575387ef8e Mon Sep 17 00:00:00 2001
From: Daniel Rainer <daniel.rainer@localhost>
Date: Thu, 15 May 2025 22:35:05 +0200
Subject: [PATCH] Update translation docs

This is done in accordance with the recent changes to our translation pipeline.
---
 CONTRIBUTING.rst | 76 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 63 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 3dd75829d..4912e9418 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -286,14 +286,57 @@ Contributing Translations
 Fish uses the GNU gettext library to translate messages from English to
 other languages.
 
-Creating and updating translations requires the Gettext tools, including
-``xgettext``, ``msgfmt`` and ``msgmerge``. Translation sources are
+Translation sources are
 stored in the ``po`` directory, named ``LANG.po``, where ``LANG`` is the
-two letter ISO 639-1 language code of the target language (eg ``de`` for
-German).
+two letter ISO 639-1 language code of the target language (e.g. ``de`` for
+German). A region specifier can also be used (e.g. ``pt_BR`` for Brazilian Portuguese).
 
-To create a new translation, run ``build_tools/update_translations.fish po/LANG.po``.
-If you add/remove/change a translatable strings, run ``build_tools/update_translations.fish`` to propagate this to all translation files (``po/*.po`).
+Adding translations for a new language
+--------------------------------------
+
+Creating new translations requires the Gettext tools.
+More specifically, you will need ``msguniq`` and ``msgmerge`` for creating translations for a new
+language.
+In addition, the ``cargo-expand`` tool is required.
+If you have ``cargo`` installed, run::
+
+  cargo install --locked --version 1.0.106 cargo-expand
+
+to install ``cargo-expand`` (Note that other versions might not work correctly with our scripts).
+To create a new translation, run::
+
+    build_tools/update_translations.fish po/LANG.po
+
+By default, this also creates ``mo`` files, which contain the information from the ``po`` files in a
+binary format.
+Fish needs these files to for actually translating at runtime.
+They are not tracked in version control, but they can help translators check if their translations
+show up correctly.
+If you build fish locally (``cargo build``), and then run the resulting binary,
+it will make use of the ``mo`` files generated by the script.
+Use the ``LANG`` environment variable to tell fish which language to use, e.g.::
+
+  LANG=pt_BR.utf8 target/debug/fish
+
+If you do not care about the ``mo`` files you can pass the ``--no-mo`` flag to the
+``update_translations.fish`` script.
+
+Modifying existing translations
+-------------------------------
+
+If you want to work on translations for a language which already has a corresponding ``po`` file, it
+is sufficient to edit this file. No other changes are necessary.
+
+To see your translations in action you can run::
+
+  build_tools/update_translations.fish --only-mo po/LANG.po
+
+to update the binary ``mo`` used by fish. Check the information for adding new languages for a
+description on how you can get fish to use these files.
+Running this script requires a fish executable and the gettext ``msgfmt`` tool.
+
+Editing PO files
+----------------
 
 Many tools are available for editing translation files, including
 command-line and graphical user interface programs. For simple use, you can use your text editor.
@@ -301,9 +344,10 @@ command-line and graphical user interface programs. For simple use, you can use
 Open up the po file, for example ``po/sv.po``, and you'll see something like::
 
   msgid "%ls: No suitable job\n"
-  msgstr "" 
+  msgstr ""
 
-The ``msgid`` here is the "name" of the string to translate, typically the english string to translate. The second line (``msgstr``) is where your translation goes.
+The ``msgid`` here is the "name" of the string to translate, typically the English string to translate.
+The second line (``msgstr``) is where your translation goes.
 
 For example::
 
@@ -316,11 +360,17 @@ Also any escaped characters, like that ``\n`` newline at the end, should be kept
 
 Our tests run ``msgfmt --check-format /path/to/file``, so they would catch mismatched placeholders - otherwise fish would crash at runtime when the string is about to be used.
 
-Be cautious about blindly updating an existing translation file. Trivial
-changes to an existing message (eg changing the punctuation) will cause
-existing translations to be removed, since the tools do literal string
-matching. Therefore, in general, you need to carefully review any
-recommended deletions.
+Be cautious about blindly updating an existing translation file.
+``msgid`` strings should never be updated manually, only by running the appropriate script.
+
+Modifications to strings in source files
+----------------------------------------
+
+If a string changes in the sources, the old translations will no longer work.
+They will be preserved in the ``po`` files, but commented-out (starting with ``#~``).
+If you add/remove/change a translatable strings in a source file,
+run ``build_tools/update_translations.fish`` to propagate this to all translation files (``po/*.po``).
+This is only relevant for developers modifying the source files of fish or fish scripts.
 
 Setting Code Up For Translations
 --------------------------------