From 2577da9ebdba13fbe99ae5ee8bde35f7ed60f6d1 Mon Sep 17 00:00:00 2001 From: Lasse Collin Date: Thu, 23 Sep 2010 14:03:10 +0300 Subject: [PATCH] Add translations.bash and translation notes to README. translations.bash prints some messages from xz, which hopefully makes it a bit easier to test translations. --- README | 96 +++++++++++++++++++++++++++++++++++++-- debug/translation.bash | 100 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+), 4 deletions(-) create mode 100644 debug/translation.bash diff --git a/README b/README index cbe95578..d6cfda78 100644 --- a/README +++ b/README @@ -9,8 +9,9 @@ XZ Utils 1.3. Documentation for liblzma 2. Version numbering 3. Reporting bugs - 4. Other implementations of the .xz format - 5. Contact information + 4. Translating the xz tool + 5. Other implementations of the .xz format + 6. Contact information 0. Overview @@ -187,7 +188,94 @@ XZ Utils system. -4. Other implementations of the .xz format +4. Translating the xz tool +-------------------------- + + The messages from the xz tool have been translated into a few + languages. Before starting to translate into a new language, ask + the author that someone else hasn't already started working on it. + + Test your translation. Testing includes comparing the translated + output to the original English version by running the same commands + in both your target locale and with LC_ALL=C. Ask someone to + proof-read and test the translation. + + Testing can be done e.g. by installing xz into a temporary directory: + + ./configure --disable-shared --prefix=/tmp/xz-test + # + make -C po update-po + make install + bash debug/translations.bash | less + bash debug/translations.bash | less -S # For --list outputs + + Repeat the above as needed (no need to re-run configure though). + + Note especially the following: + + - The output of --help and --long-help must look nice on + a 80-column terminal. It's OK to add extra lines if needed. + + - In contrast, don't add extra lines to error messages and such. + They are often preceded with e.g. a filename on the same line, + so you have no way to predict where to put a \n. Let the terminal + do the wrapping even if it looks ugly. Adding new lines will be + even uglier in the generic case even if it looks nice in a few + limited examples. + + - Be careful with column alignment in tables and table-like output + (--list, --list --verbose --verbose, --info-memory, --help, and + --long-help): + + * All descriptions of options in --help should start in the + same column (but it doesn't need to be the same column as + in the English messages; just be consistent if you change it). + Check that both --help and --long-help look OK, since they + share several strings. + + * --list --verbose and --info-memory print lines that have + the format "Description: %s". If you need a longer + description, you can put extra space between the colon + and %s. Then you may need to add extra space to other + strings too so that the result as a whole looks good (all + values start at the same column). + + * The columns of the actual tables in --list --verbose --verbose + should be aligned properly. Abbreviate if necessary. It might + be good to keep at least 2 or 3 spaces between column headings + and avoid spaces in the headings so that the columns stand out + better, but this is a matter of opinion. Do what you think + looks best. + + - Be careful to put a period at the end of a sentence when the + original version has it, and don't put it when the original + doesn't have it. Similarly, be careful with \n characters + at the beginning and end of the strings. + + - Read the TRANSLATORS comments that have been extracted from the + source code and included in xz.pot. If they suggest testing the + translation with some type of command, do it. If testing needs + input files, use e.g. tests/files/good-*.xz. + + - When updating the translation, read the fuzzy (modified) strings + carefully, and don't mark them as updated before you actually + have updated them. Reading through the unchanged messages can be + good too; sometimes you may find a better wording for them. + + - If you find language problems in the original English strings, + feel free to suggest improvements. Ask if something is unclear. + + - The translated messages should be understandable (sometimes this + may be a problem with the original English messages too). Don't + make a direct word-by-word translation from English especially if + the result doesn't sound good in your language. + + In short, take your time and pay attention to the details. Making + a good translation is not a quick and trivial thing to do. The + translated xz should look as polished as the English version. + + +5. Other implementations of the .xz format ------------------------------------------ 7-Zip and the p7zip port of 7-Zip support the .xz format starting @@ -202,7 +290,7 @@ XZ Utils http://tukaani.org/xz/embedded.html -5. Contact information +6. Contact information ---------------------- If you have questions, bug reports, patches etc. related to XZ Utils, diff --git a/debug/translation.bash b/debug/translation.bash new file mode 100644 index 00000000..df4210dd --- /dev/null +++ b/debug/translation.bash @@ -0,0 +1,100 @@ +#!/bin/bash + +############################################################################### +# +# Script to check output of some translated messages +# +# This should be useful for translators to check that the translated strings +# look good. This doesn't make xz print all possible strings, but it should +# cover most of the cases where mistakes can easily happen. +# +# Give the path and filename of the xz executable as an argument. If no +# arguments are given, this script uses ../src/xz/xz (relative to the +# location of this script). +# +# You may want to pipe the output of this script to less -S to view the +# tables printed by xz --list on a 80-column terminal. On the other hand, +# viewing the other messages may be better without -S. +# +############################################################################### +# +# Author: Lasse Collin +# +# This file has been put into the public domain. +# You can do whatever you want with this file. +# +############################################################################### + +set -e + +# If an argument was given, use it to set the location of the xz executable. +unset XZ +if [ -n "$1" ]; then + XZ=$1 + [ "x${XZ:0:1}" != "x/" ] && XZ="$PWD/$XZ" +fi + +# Locate top_srcdir and go there. +top_srcdir="$(cd -- "$(dirname -- "$0")" && cd .. && pwd)" +cd -- "$top_srcdir" + +# If XZ wasn't already set, use the default location. +XZ=${XZ-"$PWD/src/xz/xz"} +if [ "$(type -t "$XZ" || true)" != "file" ]; then + echo "Give the location of the xz executable as an argument" \ + "to this script." + exit 1 +fi +XZ=$(type -p -- "$XZ") + +# Print the xz version and locale information. +echo "$XZ --version" +"$XZ" --version +echo +if [ -d .git ] && type git > /dev/null 2>&1; then + echo "Source code version in $PWD:" + git describe --abbrev=4 +fi +echo +locale +echo + +# Make the test files directory the current directory. +cd tests/files + +# Put xz in PATH so that argv[0] stays short. +PATH=${XZ%/*}:$PATH + +# Some of the test commands are error messages and thus don't +# return successfully. +set +e + +for CMD in \ + "xz --foobarbaz" \ + "xz --memlimit=123abcd" \ + "xz --memlimit=40MiB -6 /dev/null" \ + "xz --memlimit=0 --info-memory" \ + "xz --memlimit-compress=1234MiB --memlimit-decompress=50MiB --info-memory" \ + "xz --verbose --verbose /dev/null | cat" \ + "xz --lzma2=foobarbaz" \ + "xz --lzma2=foobarbaz=abcd" \ + "xz --lzma2=mf=abcd" \ + "xz --lzma2=preset=foobarbaz" \ + "xz --lzma2=mf=bt4,nice=2" \ + "xz --lzma2=nice=50000" \ + "xz --help" \ + "xz --long-help" \ + "xz --list good-*lzma2*" \ + "xz --list good-1-check*" \ + "xz --list --verbose good-*lzma2*" \ + "xz --list --verbose good-1-check*" \ + "xz --list --verbose --verbose good-*lzma2*" \ + "xz --list --verbose --verbose good-1-check*" \ + "xz --list --verbose --verbose unsupported-check.xz" +do + echo "-----------------------------------------------------------" + echo + echo "\$ $CMD" + eval "$CMD" + echo +done 2>&1