From c7b7a7026affa604ee87eb127029f66e098f03e1 Mon Sep 17 00:00:00 2001
From: Frank Dana <ferdnyc@gmail.com>
Date: Tue, 5 Nov 2024 18:18:59 -0500
Subject: [PATCH] Add .po file creation to Localization doc

Since commit 487d45c1, `meson setup` will error out
if a project has an i18n configuration but is missing
the necessary set of `.po` files. (Previously, because
it wasn't tracking those files the build could be
configured first, then the files generated by building
the -update-po target.)

Since that no longer works, document the need to
create empty `.po` files in advance, and provide a
simple Bourne-shell-compatible command that
can be used for this purpose.

Fixes #12368
---
 docs/markdown/Localisation.md | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/markdown/Localisation.md b/docs/markdown/Localisation.md
index 2a31cb320bd2..4ba8ceb2a5cc 100644
--- a/docs/markdown/Localisation.md
+++ b/docs/markdown/Localisation.md
@@ -18,10 +18,11 @@ In this `po` subdirectory we need:
 - `LINGUAS`: Space separated list of languages
 - `POTFILES`: List of source files to scan for translatable strings.
 - `meson.build`: Localization specific Meson file
+- Empty translation input files for the languages in `LINGUAS`
 
 ### LINGUAS
 
-File with space separated list of languages. A sample LINGUAS might look like this.
+File with space- or newline-separated list of languages. A sample LINGUAS might look like this.
 
     aa ab ae af
 
@@ -58,6 +59,21 @@ them to their proper locations when doing an install. The second is
 that it creates a build rule to regenerate the main pot file. If you
 are using the Ninja backend, this is how you would invoke the rebuild.
 
+### Empty PO files
+
+For each language `<id>` listed in `LINGUAS`,
+create a file `<id>.po` in the `po/` directory.
+These can be empty files;
+we'll regenerate them later when updating the translations.
+
+If using a system with Bourne shell compatible scripting,
+empty `.po` files can be generated by running this command
+from the project root directory:
+
+```console
+$ while read _l < po/LINGUAS; do touch po/${_l}.po; done
+```
+
 ### generate .pot file
 
 Then we need to generate the main pot file. The potfile can have any
@@ -73,11 +89,16 @@ e.g. proper copyright and contact information.
 $ meson compile intltest-pot
 ```
 
-### generate .po files
+### Update .po files
 
-For each language listed in the array above we need a corresponding
-`.po` file. Those can be generated by running the following command
-from your build folder.
+For each language listed in the array above,
+Meson will update the corresponding `.po` file
+from the data in the generated `.pot` file.
+Any existing translations will be preserved,
+and data for any missing strings will be added.
+Updating the translation files
+(or generating initial data, if they were created blank)
+can be done by running this command from your build directory:
 
 ```console
 $ meson compile intltest-update-po