sh - Shell Script
-----------------

RPMs
     bash, gettext

Ubuntu packages
     bash, gettext-base

File extension
     sh

String syntax
     "abc", 'abc', abc

gettext shorthand
     "`gettext \"abc\"`"

gettext/ngettext functions
     gettext, ngettext programs

     eval_gettext, eval_ngettext, eval_pgettext, eval_npgettext shell functions

textdomain
     environment variable TEXTDOMAIN

bindtextdomain
     environment variable TEXTDOMAINDIR

setlocale
     automatic

Prerequisite
     . gettext.sh

Use or emulate GNU gettext
     use

Extractor
     xgettext

Formatting with positions
     ---

Portability
     fully portable

po-mode marking
     ---

An example is available in the examples directory: hello-sh.

Preparing Shell Scripts for Internationalization
................................................

Preparing a shell script for internationalization is conceptually similar to the steps described in Sources.  The concrete steps for shell scripts are as follows.

 1. Insert the line

          . gettext.sh

     near the top of the script.  gettext.sh is a shell function library that provides the functions eval_gettext (see eval_gettext Invocation), eval_ngettext (see eval_ngettext Invocation), eval_pgettext (see eval_pgettext Invocation), and eval_npgettext (see eval_npgettext Invocation). You have to ensure that gettext.sh can be found in the PATH.

 2. Set and export the TEXTDOMAIN and TEXTDOMAINDIR environment variables.  Usually TEXTDOMAIN is the package or program name, and TEXTDOMAINDIR is the absolute pathname corresponding to $prefix/share/locale, where $prefix is the installation location.

          TEXTDOMAIN=@PACKAGE@
          export TEXTDOMAIN
          TEXTDOMAINDIR=@LOCALEDIR@
          export TEXTDOMAINDIR

 3. Prepare the strings for translation, as described in Preparing Strings.

 4. Simplify translatable strings so that they don't contain command substitution ("`...`" or "$(...)"), variable access with defaulting (like ${VARIABLE-DEFAULT}), access to positional arguments (like $0, $1, ...) or highly volatile shell variables (like $?). This can always be done through simple local code restructuring. For example,

          echo "Usage: $0 [OPTION] FILE..."

     becomes

          program_name=$0
          echo "Usage: $program_name [OPTION] FILE..."

     Similarly,

          echo "Remaining files: `ls | wc -l`"

     becomes

          filecount="`ls | wc -l`"
          echo "Remaining files: $filecount"

 5. For each translatable string, change the output command echo or $echo to gettext (if the string contains no references to shell variables) or to eval_gettext (if it refers to shell variables), followed by a no-argument echo command (to account for the terminating newline). Similarly, for cases with plural handling, replace a conditional echo command with an invocation of ngettext or eval_ngettext, followed by a no-argument echo command.

     When doing this, you also need to add an extra backslash before the dollar sign in references to shell variables, so that the eval_gettext function receives the translatable string before the variable values are substituted into it. For example,

          echo "Remaining files: $filecount"

     becomes

          eval_gettext "Remaining files: \$filecount"; echo

     If the output command is not echo, you can make it use echo nevertheless, through the use of backquotes. However, note that inside backquotes, backslashes must be doubled to be effective (because the backquoting eats one level of backslashes). For example, assuming that error is a shell function that signals an error,

          error "file not found: $filename"

     is first transformed into

          error "`echo \"file not found: \$filename\"`"

     which then becomes

          error "`eval_gettext \"file not found: \\\$filename\"`"

Contents of gettext.sh
......................

gettext.sh, contained in the run-time package of GNU gettext, provides the following:

  * $echo The variable echo is set to a command that outputs its first argument and a newline, without interpreting backslashes in the argument string.

  * eval_gettext See eval_gettext Invocation.

  * eval_ngettext See eval_ngettext Invocation.

  * eval_pgettext See eval_pgettext Invocation.

  * eval_npgettext See eval_npgettext Invocation.

Invoking the gettext program
............................

     [file rt-gettext.texi not included]

Note: xgettext supports only the one-argument form of the gettext invocation, where no options are present and the TEXTDOMAIN is implicit, from the environment.

Invoking the ngettext program
.............................

     [file rt-ngettext.texi not included]

Note: xgettext supports only the three-arguments form of the ngettext invocation, where no options are present and the TEXTDOMAIN is implicit, from the environment.

Invoking the envsubst program
.............................

     [file rt-envsubst.texi not included]

Invoking the eval_gettext function
..................................

     eval_gettext MSGID

This function outputs the native language translation of a textual message, performing dollar-substitution on the result.  Note that only shell variables mentioned in MSGID will be dollar-substituted in the result.

Invoking the eval_ngettext function
...................................

     eval_ngettext MSGID MSGID-PLURAL COUNT

This function outputs the native language translation of a textual message whose grammatical form depends on a number, performing dollar-substitution on the result.  Note that only shell variables mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the result.

Invoking the eval_pgettext function
...................................

     eval_pgettext MSGCTXT MSGID

This function outputs the native language translation of a textual message in the given context MSGCTXT (see Contexts), performing dollar-substitution on the result.  Note that only shell variables mentioned in MSGID will be dollar-substituted in the result.

Invoking the eval_npgettext function
....................................

     eval_npgettext MSGCTXT MSGID MSGID-PLURAL COUNT

This function outputs the native language translation of a textual message whose grammatical form depends on a number in the given context MSGCTXT (see Contexts), performing dollar-substitution on the result.  Note that only shell variables mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the result.