diff options
author | bill-auger <mr.j.spam.me@gmail.com> | 2020-07-29 20:27:12 -0400 |
---|---|---|
committer | bill-auger <mr.j.spam.me@gmail.com> | 2022-08-29 02:03:43 -0400 |
commit | 0016b54fb1fa806dda0a71f41ce633bf0c9bf5a2 (patch) | |
tree | aea8e64e658379277aec32ebbc193c267ac7ed41 /HACKING | |
parent | c2659fada45f82cd5f620a685270122de9789a26 (diff) |
update docs
Diffstat (limited to 'HACKING')
-rw-r--r-- | HACKING/licensing.md | 8 | ||||
-rw-r--r-- | HACKING/translations.md | 98 |
2 files changed, 101 insertions, 5 deletions
diff --git a/HACKING/licensing.md b/HACKING/licensing.md index 6d17e31..ec83689 100644 --- a/HACKING/licensing.md +++ b/HACKING/licensing.md @@ -6,14 +6,12 @@ New code should (please) be licensed GPLv2+. I say v2 instead of v3 because some code from Arch is GPLv2 (no "or any later version"), and having to worry about which programs can be combined is a huge pain. -Copyright statements should look like +Copyright statements for most code, should be of the form: # Copyright (C) YEARS NAME <EMAIL> -for most code, for 3rd-party code that has been imported, indent it a -bit: +For 3rd-party code, which has been imported, indent it a bit: # Copyright (C) YEARS NAME <EMAIL> -Always put a line with `# License:` specifying the license of that -file. +Always put a `# License:` line specifying the license of that file. diff --git a/HACKING/translations.md b/HACKING/translations.md new file mode 100644 index 0000000..2229d2a --- /dev/null +++ b/HACKING/translations.md @@ -0,0 +1,98 @@ +Translations for programs are provided in files with the `.po` suffix. These are +created by copying PO-template (`.pot`) files, and filling in the missing +"msgstr" values. + +To add a translation, you'll first (1) need to create the `.pot` files if you +don't already have them, and then (2) copy them and (3) fill them in. + +## 1. Create the `.pot` files + +If you are working from a release source tarball, you can skip this step (the +`.pot` files are included in the tarball); if you are working from git, read on. + +libretools' .pot files are not tracked in git; they are created by running +`make`. You'll need a checkout of both 'devtools-par' and 'libretools' to run +`make` if building from git. The 'devtools-par' and 'libretools' source root +directories should have the same parent directory. + + $ git clone https://git.parabola.nu/packages/libretools.git/ + $ git clone https://git.parabola.nu/packages/devtools-par.git/ + $ cd libretools + $ make po/files.generate + $ cd po/ + $ ls + gitget.pot + librelib.pot + libretools.pot + +NOTE: If you have modified the libretools source code, that may cause errors +during translation; especially if you have modified any of the translatable +strings. The failure will be evident by the error message: + + msgcmp: found N fatal errors + +If you see this error, refer to the "Updating translations" section below. + +## 2. Create the `.po` Files + +Create a folder under `po/` with the two-letter language code[^1] you want to +add. Then, copy the `.pot` files to that folder, changing the file extension to +`.po`. Finally, link the `subdir.mk` file as the Makefile for that directory. +For example: + + $ mkdir es + $ for file in *.pot; do cp $file es/${file%t}; done + $ ln -s ../subdir.mk es/Makefile + +[^1]: See the langauge code table: <http://www.lingoes.net/en/translator/langcode.htm> + +## 3. Fill the `.po` Files + +From there you can open each .po file in your favorite text editor, and fill in +the `msgstr` values with translations of the associated `msgid` keys. + +## 4. Synchronizing/Updating Translations + +If you have modified the libretools source code, it is likely that the program +will fail to compile, due to the translation files being mis-aligned with the +latest changes. You will need to run `msgmerge` to merge the newly generated +.pot templates into the existing .po files, as indicated by the `msgcmp` command +trace in the build log. + +e.g. if the following error message appeers after this log trace: + + msgcmp --use-untranslated --use-fuzzy po/es/libretools.po po/libretools.pot + .... + msgcmp: found 42 fatal errors + +then run: + + $ msgmerge po/es/libretools.po po/libretools.pot + +Notice any red (fuzzy) lines. Those are relatively minor mis-matches, which the +tool was able to reconcile, but may need correction. Also notice any green, +commented-out, 'msgid'/'msgstr' line pairs. Those are unresolved mis-matches, +which definitely need correction. They may correspond to a new 'msgid'/'msgstr' +line pair in the `msgmerge` output, with the new text as 'msgid', and an empty +'msgstr'; but the changes were too significant for the tool to determine the +correlation. The standard output of `msgmerge` is the raw text for a new +replacemnt .po file. Next, direct the output to a file, make the corrections +to the replacemnt .po file, using the `msgmerge` output as a guide; then replace +the failed .po file with the new corrected file. + + $ msgmerge po/es/libretools.po po/libretools.pot > po/es/libretools.po-merged + $ mv po/es/libretools.po{-merged,} + +Alternatively, a merge tool such as `meld`, is especially helpful for this task. +A merge tool should highlight the same merge conflicts, shown in the the +`msgmerge` output, as a side-by-side comparison, allowing you to merge the +changes from the generated '-merged' file, into the tracked .po file, in-place. +In order to minimize the possible merge conflict next time, it is best to merge +all of the changes, especially the comments with line numbers. + + $ meld po/es/libretools.po{-merged,} + +Once `make clean && make` is able to complete successfully, commit the new .po +file to the VCS. + + $ git commit -m 'sync translations' po/es/libretools.po |