[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
howtos:misc:internationalization_and_localization_of_shell_scripts [2013/05/20 18:12 (UTC)] – [Internationalization process] didierspaier | howtos:misc:internationalization_and_localization_of_shell_scripts [2015/06/26 19:33 (UTC)] – [Presentation] Wrong quoting fixed didierspaier | ||
---|---|---|---|
Line 7: | Line 7: | ||
This document is intended to help developers, maintainers and translators to write/ | This document is intended to help developers, maintainers and translators to write/ | ||
- | The reference document is the manual entitled [[http:// | + | The reference document is the manual entitled [[http:// |
The manual encompasses all programming languages usable with gettext, with a special focus on the C language. | The manual encompasses all programming languages usable with gettext, with a special focus on the C language. | ||
Line 64: | Line 64: | ||
In below diagrams gettext programs are surrounded by square brackets. | In below diagrams gettext programs are surrounded by square brackets. | ||
- | === Internationalization === | + | === (1) Internationalization === |
Line 76: | Line 76: | ||
- | === Localization (example for French and Dutch languages). === | + | === (2) Localization (example for French and Dutch languages). === |
Line 100: | Line 100: | ||
- | === Usage === | + | === (3) Usage === |
Let's assume that one of the scripts, " | Let's assume that one of the scripts, " | ||
Line 119: | Line 119: | ||
- | === Maintenance === | + | === (4) Maintenance === |
Maintenance process can be triggered by a script' | Maintenance process can be triggered by a script' | ||
Line 138: | Line 138: | ||
| | ||
- | Maintenance process can be triggered as well by a modification of a language | + | Maintenance process can be triggered as well by a modification of a messages |
This variant of the process is shorter: | This variant of the process is shorter: | ||
Line 174: | Line 174: | ||
But the replacement only occurs if following conditions are fulfilled: | But the replacement only occurs if following conditions are fulfilled: | ||
- | * A MO file is available in the path computed from the TEXTDOMAIN environment variable as < | + | * A MO file is available in the path computed from the TEXTDOMAIN environment variable as < |
* TEXTDOMAIN variable is exported before any *gettext command occurs. | * TEXTDOMAIN variable is exported before any *gettext command occurs. | ||
* gettext.sh, which provides the eval_gettext and eval_ngettext functions, is sourced before any occurrence of one of these functions. | * gettext.sh, which provides the eval_gettext and eval_ngettext functions, is sourced before any occurrence of one of these functions. | ||
Line 182: | Line 182: | ||
* If the text string includes a parameter expansion, eval_gettext is used instead of gettext. | * If the text string includes a parameter expansion, eval_gettext is used instead of gettext. | ||
* "The variable names must consist solely of alphanumeric or underscore | * "The variable names must consist solely of alphanumeric or underscore | ||
- | * Parameter expansions are escaped with a single backslash like this:\\ \$parameter or \${parameter}, unless the eval_gettext command be inside a command substitution like this:\\ `eval_gettext " | + | * Parameter expansions are escaped with a single backslash like this:\\ \$parameter or \${parameter}\\ unless the eval_gettext command be inside a command substitution like this: |
* Only the forms $parameter and ${parameter} of parameter expansion are used inside an eval_gettext' | * Only the forms $parameter and ${parameter} of parameter expansion are used inside an eval_gettext' | ||
* Positional parameters, special parameters and command substitutions are *not* used inside a gettext' | * Positional parameters, special parameters and command substitutions are *not* used inside a gettext' | ||
Line 195: | Line 195: | ||
I recommend to mark messages: | I recommend to mark messages: | ||
* arguments of a not redirected ' | * arguments of a not redirected ' | ||
- | * arguments of redirected ' | + | * arguments of redirected ' |
- | * arguments of other commands which displays the message, for instance | + | * arguments of other commands which displays the message, for instance the ' |
On the contrary I recommend not to mark: | On the contrary I recommend not to mark: | ||
Line 208: | Line 208: | ||
=== Use ' | === Use ' | ||
- | The choice to produce only one POT file for the software as a whole or to make one POT files per set of scripts have to be made, considering for instance which choice will minimize maintenance work, how localization' | + | The choice to produce only one POT file for the software as a whole or to make one POT files per set of scripts have to be made, considering for instance which choice will minimize maintenance work, how localizations |
I'm inclined to produce only one POT file, but the choice is yours. | I'm inclined to produce only one POT file, but the choice is yours. | ||
Line 216: | Line 216: | ||
The POT file will be generated using the ' | The POT file will be generated using the ' | ||
- | I suggest to include | + | Include |
-L Shell (of course!) | -L Shell (of course!) | ||
--strict (to facilitate checks and management of the messages catalogs) | --strict (to facilitate checks and management of the messages catalogs) | ||
Line 253: | Line 253: | ||
I suggest to use an UTF-8 locale, as for reading this document. | I suggest to use an UTF-8 locale, as for reading this document. | ||
- | If the user is polyglot, another option is to set gettext' | + | If the user is polyglot, another option is to set gettext' |
For instance, if LANGUAGE is set to ' | For instance, if LANGUAGE is set to ' | ||
Line 265: | Line 265: | ||
The translators will use the new POT file to update their respective (saved) PO files with the ' | The translators will use the new POT file to update their respective (saved) PO files with the ' | ||
- | Then they will edit/ | + | Then they will edit/ |
After that the PO file will be checked against the POT file with ' | After that the PO file will be checked against the POT file with ' | ||
Line 273: | Line 273: | ||
==== Practical recommendations for developers and maintainers ==== | ==== Practical recommendations for developers and maintainers ==== | ||
- | Many English words are polysemous: their meaning can only be determined from the context of their usage. | + | Many English words are polysemous: their meaning can only be determined from the context of their usage. |
As a practical consequence, | As a practical consequence, | ||
Example: recently, while downloading a software I saw something like this:\\ 31min gauche\\ Go figure? After a while I realized that " | Example: recently, while downloading a software I saw something like this:\\ 31min gauche\\ Go figure? After a while I realized that " | ||
- | Also, the order of words in a sentence vary upon the languages, furthermore not all languages are written left to right. | + | Also, order of words in a sentence vary upon language, furthermore not all languages are written left to right. |
- | + | ||
- | So I suggest to mark entire paragraphs, or at least entire sentences, not lines, let alone isolated words but in special cases. | + | |
For instance, if text paragraphs were split in lines displayed by ' | For instance, if text paragraphs were split in lines displayed by ' | ||
- | Do not fear to include the variable substitutions in the sentences, | + | Do not fear to include the variable substitutions in the sentences, PO editor will check that they be present as is in the translations. |
=== Recommendations for ' | === Recommendations for ' | ||
Line 307: | Line 303: | ||
In particular, I recommend to favor options which take as first argument a text string instead of a file, to allow line wrapping. It is still possible to preserve the intended layout using white spaces for indentation. | In particular, I recommend to favor options which take as first argument a text string instead of a file, to allow line wrapping. It is still possible to preserve the intended layout using white spaces for indentation. | ||
- | For instance,\\ dialog < | + | For instance, |
+ | | ||
+ | can be replaced with | ||
+ | | ||
==== Practical recommendations for translators ==== | ==== Practical recommendations for translators ==== | ||
- | Depending on amount of work needed and available resources, there can be one translator or a team of translators per target language. | + | Depending on amount of work needed and available resources, there can be one translator or a team of translators per target language. In all cases, I recommend that at least one person be responsible for organizing the team's work, checking the translations and transmitting the checked PO file to the maintainer(s). Let's call this person the team coordinator. |
- | In all cases, I recommend that one person be responsible for organizing the team's work, checking | + | Don't feel obliged to translate verbatim. Not only is this rarely |
- | To qualify as a translator, a person should in my opinion have enough ability of reading shell scripts to understand the meaning | + | Use a specialized PO editor, ' |
- | Not only is this rarely the best way to convey | + | While translating, |
- | It is highly advisable that translators use a specialized PO editor or the PO mode of an editor like VIM or Emacs. | + | If possible, check the layout |
- | This will not only prevent inadvertently editing | + | This is especially important if you are translating dialog boxes. In particular, take care not to write too long sentences on one single line if it appears that the text can't flow on next one. |
- | For instance ' | + | Bear in mind that in VGA mode (used in text installers, in particular), |
- | If possible, I suggest | + | Do not add question marks that are not present in the original message. |
- | You could do that looking at the context | + | If the message refers to tags (text on the buttons) of dialog boxes, like " |
- | This is especially important if you are translating dialog boxes. | + | Avoid colloquialisms and technical slang. |
- | In particular, take care not to write too long sentences on one single | + | To " |
- | Bear in mind that in VGA mode (used in text installers, in particular), the width of line is limited theoretically to 80 characters, but practically often to 74. | + | In addition, you will have to comply to gettext' |
+ | * If a word beginning with a dollar sign is included | ||
+ | * The translation | ||
+ | * A single backslash character " | ||
- | Do not add question marks that are not present | + | To " |
- | If the message refers to tags (text on the buttons) of dialog boxes, like " | + | To check your translation against gettext' |
+ | msgfmt -c <name of the PO file> | ||
- | I suggest to avoid colloquialisms and technical slang. | + | ==== Warning |
- | In addition, you will have to comply to gettext's requirements fot it to work: | + | Preserve carefully syntax of man pages found in English markup. For instance don't replace: |
- | * If a word beginning with a dollar sign is included in the original text it should be present in the translation with exactly the same spelling. | + | |
- | * The translation should or not begin or end with a " | + | |
- | * a single backslash character " | + | |
- | To check your translation against gettext's requirements you could run | + | * 'B<' with 'B <' (don't insert a space) |
- | following command: | + | |
- | | + | * " |
+ | |||
+ | When translating shell commands, preserve English names of paths when needed. But you may and should translate arguments to be replaced by a value like ' | ||
+ | |||
+ | Didier Spaier | ||
====== Sources ====== | ====== Sources ====== | ||
* Originally written by [[wiki: | * Originally written by [[wiki: | ||
- | {{tag> | + | {{tag> |