Update Lazarus Translation Files with updatepofiles

You will refresh a Lazarus .pot catalogue from compiled resource string files, then merge the new messages into the translated .po files beside it. The guide uses the Lazarus 3.0 tool installed here from lcl-utils-3.0, package version 3.0+dfsg1-8build3.

Allow about fifteen minutes for a small project. You need a shell, a project translation directory, at least one .pot file, and the relevant Lazarus resource files. This tool changes translation files, so make a backup or use version control before running it. No elevated privilege is normally required.

1. Check which updatepofiles you are running

The unversioned command is an alternatives-managed link on this machine. Confirm that it resolves to the Lazarus 3.0 executable and record the package version:

$ command -v updatepofiles
/usr/bin/updatepofiles
$ readlink -f "$(command -v updatepofiles)"
/usr/lib/lazarus/3.0/tools/updatepofiles
$ dpkg-query -W -f='${Package} ${Version}\n' lcl-utils-3.0
lcl-utils-3.0 3.0+dfsg1-8build3

Use updatepofiles-3.0 when a script must select this release explicitly. The ordinary command is convenient for interactive work, but an alternatives change could make it point at another installed Lazarus release later.

Checkpoint: ask the installed binary for its usage text:

$ updatepofiles
Usage: updatepofiles [--searchdir=<dir>] [filenameA.rsj [filenameB.rsj ... filenameN.rsj]] filename1.pot [filename2.pot ... filenameN.pot]

The local manual page is older than the installed program: it describes .po arguments and says there are no options. Follow the usage printed by the installed binary for this package. Do not treat --help or --version as supported options; on this installation they are read as filenames and produce an invalid-extension message.

2. Make a recoverable copy

Run this from the directory containing your translation files, or replace the path with an explicit project directory:

$ cd /path/to/project/translations
$ cp -a . "backup-before-updatepofiles-$(date +%Y%m%d-%H%M%S)"
$ find . -maxdepth 1 -type f \( -name '*.pot' -o -name '*.po' \) -print | sort

The command can update the .pot file and its translated .po companions. If the files are tracked, a clean working tree is an equally good recovery point. Do not run this against a production checkout without first checking what the backup or version-control diff will contain.

3. Update a POT file from resource strings

A resource file can be supplied before the catalogue it belongs to. The installed tool accepts .rsj, plus the older .rst and .lrj resource extensions:

$ updatepofiles \
    /path/to/build/lib/messages.rsj \
    /path/to/project/translations/project.pot

The resource argument associates strings with the next .pot argument. You can repeat the pair for separate projects:

$ updatepofiles \
    /path/to/build/app.rsj /path/to/app/translations/app.pot \
    /path/to/build/tools.rsj /path/to/tools/translations/tools.pot

There is normally no success message. Verify that the catalogue changed as expected:

$ git diff -- project.pot
$ rg -n '^msgid ' project.pot | tail

Do not assume that every resource string belongs in every catalogue. Pair each resource file with the correct .pot, and inspect the diff for unrelated messages before committing it.

4. Let the tool find resource files

Use --searchdir=<dir> when a resource filename is not in the current directory. The search covers that directory and its subdirectories:

$ updatepofiles \
    --searchdir=/path/to/build \
    messages.rsj \
    /path/to/project/translations/project.pot
Current resource string table file search directory: "/path/to/build"

Give the resource basename, not a guessed path. If the file cannot be found, the command reports an error and the catalogue is not a reliable result. Check the exact name first:

$ find /path/to/build -type f -name 'messages.rsj' -print
/path/to/build/lcl/messages.rsj

Checkpoint: if find prints nothing, stop and fix the build output or the search directory. Do not create an empty resource file just to satisfy the command.

5. Merge the translated PO files

When the .pot is updated, updatepofiles also merges new messages into translated files matching the catalogue's project name, such as project.fr.po or project.de.po. A simple run with only the catalogue is enough:

$ updatepofiles /path/to/project/translations/project.pot
$ git diff --stat -- /path/to/project/translations
$ git diff -- /path/to/project/translations/project.pot \
    /path/to/project/translations/project.*.po

New entries should be visible as untranslated messages in the language files. Existing translations are data, not proof that a message is still correct: review changed, fuzzy or empty entries with your normal translation workflow.

Do not grant root access merely because a file is unwritable. If the project directory belongs to another account, stop and resolve ownership or permissions with its administrator. Running the updater as root can leave the whole checkout owned by root and makes the recovery path harder.

6. Recover from an unwanted update

Before committing, discard only the files you deliberately inspected. For a Git checkout, restore the catalogue and language files from the last commit:

$ git restore -- project.pot project.fr.po project.de.po
$ git status --short

If you used the timestamped backup instead, copy the required files back after comparing them. Do not use a broad recursive delete or restore command when the directory contains unrelated work. After recovery, rerun the updater with the corrected resource-to-catalogue pairing and inspect the diff again.