aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLasse Collin <lasse.collin@tukaani.org>2010-09-23 14:03:10 +0300
committerLasse Collin <lasse.collin@tukaani.org>2010-09-23 14:03:10 +0300
commit2577da9ebdba13fbe99ae5ee8bde35f7ed60f6d1 (patch)
treeab4bd4711d994fd2180adb2591d5e1fbe6b38e7c
parentxz: Update the Czech translation. (diff)
downloadxz-2577da9ebdba13fbe99ae5ee8bde35f7ed60f6d1.tar.xz
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.
-rw-r--r--README96
-rw-r--r--debug/translation.bash100
2 files changed, 192 insertions, 4 deletions
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
+ # <Edit the .po file in the po directory.>
+ 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