[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.

Welcome to the Slackware Documentation Project

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
howtos:misc:internationalization_and_localization_of_shell_scripts [2013/08/09 19:56 (UTC)] – [Practical recommendations for translators] didierspaierhowtos:misc:internationalization_and_localization_of_shell_scripts [2015/12/22 22:31 (UTC)] (current) – [Processes diagrams] Typo fix didierspaier
Line 7: Line 7:
 This document is intended to help developers, maintainers and translators to write/maintain/translate internationalized then localized shell scripts, using the tools provided by GNU gettext. This document is intended to help developers, maintainers and translators to write/maintain/translate internationalized then localized shell scripts, using the tools provided by GNU gettext.
  
-The reference document is the manual entitled [[http://www.gnu.org/software/gettext/manual/gettext.html|GNU `gettext' utilities]].+The reference document is the manual entitled [[http://www.gnu.org/software/gettext/manual/gettext.html|GNU 'gettext' utilities]].
  
 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 55: Line 55:
  
 Among these actions are execution of some programs of the gettext suite: Among these actions are execution of some programs of the gettext suite:
-  * gettetxt: marks strings to be insternationalized, then displays localized messages during scripts' execution+  * gettetxt: marks strings to be internationalized, then displays localized messages during scripts' execution
   * xgettext: extracts marked strings from a set of shell scripts to build a POT or a PO file   * xgettext: extracts marked strings from a set of shell scripts to build a POT or a PO file
   * msgcmp:   checks a PO file against another PO or a POT file for consistency   * msgcmp:   checks a PO file against another PO or a POT file for consistency
Line 65: Line 65:
  
 === (1) Internationalization === === (1) Internationalization ===
- +
  
    Set of shell scripts ───> Preparation ───> Marked shell scripts ───╮    Set of shell scripts ───> Preparation ───> Marked shell scripts ───╮
Line 141: Line 141:
  
 This variant of the process is shorter: This variant of the process is shorter:
-   +
   ╭─ [msgcmp] <── <locale>.po <── PO editor <── <locale>.po <── Update needed   ╭─ [msgcmp] <── <locale>.po <── PO editor <── <locale>.po <── Update needed
   │   │
Line 216: Line 216:
 The POT file will be generated using the 'xgettext' command (see the manual or 'xgettext --help' for details). The POT file will be generated using the 'xgettext' command (see the manual or 'xgettext --help' for details).
  
-I suggest to include following options in the command:<code>+Include following options in the command:<code>
 -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 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, the more context you provide, the more accurate the translation can be. As a practical consequence, the more context you provide, the more accurate the translation can be.
  
 Example: recently, while downloading a software I saw something like this:\\ 31min gauche\\ Go figure? After a while I realized that "left" had been translated "gauche" (as in "left hand"). Example: recently, while downloading a software I saw something like this:\\ 31min gauche\\ Go figure? After a while I realized that "left" had been translated "gauche" (as in "left hand").
  
-Also, order of words in a sentence vary upon language, 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. Thus, mark entire paragraphs, or at least entire sentences, not lines, let alone isolated words but in special cases.
- +
-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 'echo' commands, replace all consecutive 'echo' commands by a single 'gettext' or 'eval_gettext' command. For instance, if text paragraphs were split in lines displayed by 'echo' commands, replace all consecutive 'echo' commands by a single 'gettext' or 'eval_gettext' command.
  
-Do not fear to include the variable substitutions in the sentences, the PO editor will check that they be present as is in the translations. +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 'dialog' program. === === Recommendations for 'dialog' program. ===
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 <common-options> --textbox <file> <height> <width>\\ can be replaced with\\ dialog --no-collapse <common-options> --msgbox "`cat <file>`" <height> <width>+For instance, 
 +  dialog <common-options> --textbox <file> <height> <width> 
 +can be replaced with 
 +  dialog --no-collapse <common-options> --msgbox "`cat <file>`" <height> <width>
  
 ==== 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 the translations and transmitting the checked PO file to the maintainer(s). Let's call this person the team coordinator.+Don't feel obliged to translate verbatim. Not only is this rarely the best way to convey the meaning, but in addition this often leads to sentences too long to fit in allowed space.
  
-To qualify as translator, a person should in my opinion have enough ability of reading shell scripts to understand the meaning and layout of the messages to be translated.+Use specialized PO editor'not' general text editor. This will not only prevent inadvertently editing 'msgid' strings but also facilitate their work and automatize additional checks, as the presence of a variable in the translation with the same spelling as in the original.
  
-Alsohe or she should not feel obliged to translate word for word.+While translatingchoose a serif fixed width (or "monospaced") font, like Courier. That allow to visually distinguish characters that otherwise would look the same, and check line's length when that matters.
  
-Not only is this rarely the best way to convey the meaning, but in addition this often leads to sentences too long to fit in allowed space.+If possible, check the layout of the messages. You could do that looking at the context in the relevant source file. Even better, simply run the translated script
  
-It is highly advisable that translators use a specialized PO editor or the PO mode of an editor like VIM or Emacs.+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.
  
-This will not only prevent inadvertently editing 'msgid' strings but also facilitate their work and automatize additional checks, as the presence of a variable in the translation with the same spelling as in the original.+Bear in mind that in VGA mode (used in text installers, in particular), line's width is limited theoretically to 80 characters, but practically often to 74.
  
-For instance 'lokalize' is included with Slackware Linux and 'poedit' is available @ http://slackbuilds.org.+Do not add question marks that are not present in the original message.
  
-If possible, I suggest that you check the layout of the messages.+If the message refers to tags (text on the buttons) of dialog boxes, like "OK", "Yes", "NO", "Continue", "Cancel", check how theses tags are translated in your language in dialog's interface and use the same words.
  
-You could do that looking at the context in the relevant source file.+Avoid colloquialisms and technical slang.
  
-This is especially important if you are translating dialog boxes.+To "cut" (or end) a line inside a "dialog" box you should type \n: pressing [Enter] will 'not' insert a "new line" character in the text viewed by user
  
-In particulartake care not to write too long sentences on one single line if it appears that the text can'flow on next one.+In additionyou will have to comply to gettext's requirements for it to work: 
 +  * 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 (case matters). 
 +  * The translation text should include a "new line" character (or line feed, represented by "\n") at the beginning or at the end, exactly as the original text does. Conversely, if the original text doesn’have the character, then the translation shouldn’t have it. 
 +  * A single backslash character "\" is not allowed in the translation.
  
-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.+To check your translation against gettext's requirements you could run following command: 
 +  msgfmt -c <name of the PO file>
  
-Do not add question marks that are not present in the original message.+==== Warning  about translation of man pages ====
  
-If the message refers to tags (text on the buttons) of dialog boxes, like "OK", "Yes", "NO", "Continue", "Cancel", check how theses tags are translated in your language in dialog's interface and use the same words.+Preserve carefully syntax of man pages found in English markup. For instance don't replace:
  
-I recommend avoiding colloquialisms and technical slang.+  * 'B<' with 'B <' (don't insert a space) 
 +  * 'B<' with 'b<' (keep the B as a capital letter - and don't replace it by the Greek capital letter BETA that looks the same on the screen) 
 +  * "I" with '|' (don't replace the capital letter I with a pipe symbol)
  
-In addition, you will have to comply to gettext's requirements for it to work: +When translating shell commandspreserve English names of paths when needed. But you may and should translate arguments to be replaced by a value like 'packagename'
-  * 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 (case matters). +
-  * The translation should or not begin or end with a "carriage return" character, represented by "\n", exactly as the original text does. +
-  * single backslash character "\" is not allowed in the translation.+
  
-To check your translation against gettext's requirements you could run +Didier Spaier
-following command: +
-  msgfmt -c <name of the PO file>+
  
 ====== Sources ====== ====== Sources ======
 * Originally written by [[wiki:user:didierspaier | Didier Spaier]] * Originally written by [[wiki:user:didierspaier | Didier Spaier]]
 {{tag>howtos gettext shell scripts internationalization localization i18n l10n}} {{tag>howtos gettext shell scripts internationalization localization i18n l10n}}
 +
 howtos:misc:internationalization_and_localization_of_shell_scripts ()