File: gettext.info,  Node: Top,  Next: Introduction,  Up: (dir)

GNU ‘gettext’ utilities
***********************

   This manual documents the GNU gettext tools and the GNU libintl
library, version 1.0.

* Menu:

* Introduction::                Introduction
* Users::                       The User's View
* PO Files::                    The Format of PO Files
* Sources::                     Preparing Program Sources
* Template::                    Making the PO Template File
* Creating::                    Creating a New PO File
* Updating::                    Updating Existing PO Files
* Pretranslating::              Pretranslating PO Files
* Editing::                     Editing PO Files
* Manipulating::                Manipulating PO Files
* Binaries::                    Producing Binary MO Files
* Programmers::                 The Programmer's View
* Translators::                 The Translator's View
* Maintainers::                 The Maintainer's View
* Installers::                  The Installer's and Distributor's View
* Programming Languages::       Other Programming Languages
* Data Formats::                Other Data Formats
* Conclusion::                  Concluding Remarks

* Language Codes::              ISO 639 language codes
* Country Codes::               ISO 3166 country codes
* Licenses::                    Licenses

* Program Index::               Index of Programs
* Option Index::                Index of Command-Line Options
* Variable Index::              Index of Environment Variables
* PO Mode Index::               Index of Emacs PO Mode Commands
* Autoconf Macro Index::        Index of Autoconf Macros
* Index::                       General Index

 -- The Detailed Node Listing --

Introduction

* Why::                         The Purpose of GNU ‘gettext’
* Concepts::                    I18n, L10n, and Such
* Aspects::                     Aspects in Native Language Support
* Files::                       Files Conveying Translations
* Overview::                    Overview of GNU ‘gettext’

The User's View

* System Installation::         Questions During Operating System Installation
* Setting the GUI Locale::      How to Specify the Locale Used by GUI Programs
* Setting the POSIX Locale::    How to Specify the Locale According to POSIX
* Working in a Windows console::  Obtaining good output in a Windows console
* Installing Localizations::    How to Install Additional Translations

Setting the Locale through Environment Variables

* Locale Names::                How a Locale Specification Looks Like
* Locale Environment Variables::  Which Environment Variable Specifies What
* The LANGUAGE variable::       How to Specify a Priority List of Languages

The Format of PO Files

* PO File Entries::             What an entry looks like
* Workflow flags::              Workflow flags
* Sticky flags::                Sticky flags
* Entries with Context::        Entries with Context
* Entries with Plural Forms::   Entries with Plural Forms
* More Details::                Further details on the PO file format
* PO File Format Evolution::    The PO File Format is evolving

Preparing Program Sources

* Importing::                   Importing the ‘gettext’ declaration
* Triggering::                  Triggering ‘gettext’ Operations
* Preparing Strings::           Preparing Translatable Strings
* Mark Keywords::               How Marks Appear in Sources
* Marking::                     Marking Translatable Strings
* Translator advice::           Adding advice for translators
* c-format Flag::               Telling something about the following string
* Special cases::               Special Cases of Translatable Strings
* Bug Report Address::          Letting Users Report Translation Bugs
* Names::                       Marking Proper Names for Translation
* Libraries::                   Preparing Library Sources

Making the PO Template File

* xgettext Invocation::         Invoking the ‘xgettext’ Program
* Combining POTs::              Combining PO Template Files

Creating a New PO File

* msginit Invocation::          Invoking the ‘msginit’ Program
* Header Entry::                Filling in the Header Entry

Updating Existing PO Files

* msgmerge Invocation::         Invoking the ‘msgmerge’ Program

Pretranslating PO Files

* Installing an LLM::           Installing a Large Language Model
* msgpre Invocation::           Invoking the ‘msgpre’ Program
* spit Invocation::             Invoking the ‘spit’ Program

Editing PO Files

* Web based localization::      Web-based PO editing
* Lokalize::                    KDE's PO File Editor
* Gtranslator::                 GNOME's PO File Editor
* Poedit::                      A simple PO File Editor
* OmegaT::                      A powerful Translation Editor
* Virtaal::                     The Virtaal Translation Editor
* PO Mode::                     Emacs's PO File Editor
* Vim::                         Editing PO Files in vim
* Compendium::                  Using Translation Compendia

Emacs's PO File Editor

* Installation::                Completing GNU ‘gettext’ Installation
* Main PO Commands::            Main Commands
* Entry Positioning::           Entry Positioning
* Normalizing::                 Normalizing Strings in Entries
* Translated Entries::          Translated Entries
* Fuzzy Entries::               Fuzzy Entries
* Untranslated Entries::        Untranslated Entries
* Obsolete Entries::            Obsolete Entries
* Modifying Translations::      Modifying Translations
* Modifying Comments::          Modifying Comments
* Subedit::                     Mode for Editing Translations
* C Sources Context::           C Sources Context
* Auxiliary::                   Consulting Auxiliary PO Files

Using Translation Compendia

* Creating Compendia::          Merging translations for later use
* Using Compendia::             Using older translations if they fit

Manipulating PO Files

* msgcat Invocation::           Invoking the ‘msgcat’ Program
* msgconv Invocation::          Invoking the ‘msgconv’ Program
* msggrep Invocation::          Invoking the ‘msggrep’ Program
* msgfilter Invocation::        Invoking the ‘msgfilter’ Program
* msguniq Invocation::          Invoking the ‘msguniq’ Program
* msgcomm Invocation::          Invoking the ‘msgcomm’ Program
* msgcmp Invocation::           Invoking the ‘msgcmp’ Program
* msgattrib Invocation::        Invoking the ‘msgattrib’ Program
* msgen Invocation::            Invoking the ‘msgen’ Program
* msgexec Invocation::          Invoking the ‘msgexec’ Program
* Colorizing::                  Highlighting parts of PO files
* Other tools::                 Other tools for manipulating PO files
* libgettextpo::                Writing your own programs that process PO files

Highlighting parts of PO files

* The --color option::          Triggering colorized output
* The TERM variable::           The environment variable ‘TERM’
* The --style option::          The ‘--style’ option
* Style rules::                 Style rules for PO files
* Customizing less::            Customizing ‘less’ for viewing PO files

Producing Binary MO Files

* msgfmt Invocation::           Invoking the ‘msgfmt’ Program
* msgunfmt Invocation::         Invoking the ‘msgunfmt’ Program
* MO Files::                    The Format of GNU MO Files

The Programmer's View

* catgets::                     About ‘catgets’
* gettext::                     About ‘gettext’
* Comparison::                  Comparing the two interfaces
* Using libintl.a::             Using libintl.a in own programs
* gettext grok::                Being a ‘gettext’ grok
* Temp Programmers::            Temporary Notes for the Programmers Chapter

About ‘catgets’

* Interface to catgets::        The interface
* Problems with catgets::       Problems with the ‘catgets’ interface?!

About ‘gettext’

* Interface to gettext::        The interface
* Ambiguities::                 Solving ambiguities
* Locating Catalogs::           Locating message catalog files
* Charset conversion::          How to request conversion to Unicode
* Contexts::                    Solving ambiguities in GUI programs
* Plural forms::                Additional functions for handling plurals
* Optimized gettext::           Optimization of the *gettext functions

Temporary Notes for the Programmers Chapter

* Temp Implementations::        Temporary - Two Possible Implementations
* Temp catgets::                Temporary - About ‘catgets’
* Temp WSI::                    Temporary - Why a single implementation
* Temp Notes::                  Temporary - Notes

The Translator's View

* Organization::                Organization
* Responsibilities::            Responsibilities in the Translation Project
* Dialects::                    Language dialects
* Translating plural forms::    How to fill in ‘msgstr[0]’, ‘msgstr[1]’
* Prioritizing messages::       How to find which messages to translate first

The Maintainer's View

* Flat and Non-Flat::           Flat or Non-Flat Directory Structures
* Prerequisites::               Prerequisite Works
* gettextize Invocation::       Invoking the ‘gettextize’ Program
* Adjusting Files::             Files You Must Create or Alter
* autoconf macros::             Autoconf macros for use in ‘configure.ac’
* Interfacing with the Translators::
* Version Control Issues::
* Release Management::          Creating a Distribution Tarball

Files You Must Create or Alter

* po/POTFILES.in::              ‘POTFILES.in’ in ‘po/’
* po/fetch-po::                 ‘fetch-po’ in ‘po/’
* po/LINGUAS::                  ‘LINGUAS’ in ‘po/’
* po/Makevars::                 ‘Makevars’ in ‘po/’
* po/Rules-**::                  Extending ‘Makefile’ in ‘po/’
* configure.ac::                ‘configure.ac’ at top level
* config.guess::                ‘config.guess’, ‘config.sub’ at top level
* mkinstalldirs::               ‘mkinstalldirs’ at top level
* aclocal::                     ‘aclocal.m4’ at top level
* config.h.in::                 ‘config.h.in’ at top level
* Makefile::                    ‘Makefile.in’ at top level
* src/Makefile::                ‘Makefile.in’ in ‘src/’
* lib/gettext.h::               ‘gettext.h’ in ‘lib/’

Autoconf macros for use in ‘configure.ac’

* AM_GNU_GETTEXT::              AM_GNU_GETTEXT in ‘gettext.m4’
* AM_GNU_GETTEXT_VERSION::      AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
* AM_GNU_GETTEXT_NEED::         AM_GNU_GETTEXT_NEED in ‘gettext.m4’
* AM_PO_SUBDIRS::               AM_PO_SUBDIRS in ‘po.m4’
* AM_XGETTEXT_OPTION::          AM_XGETTEXT_OPTION in ‘po.m4’
* AM_ICONV::                    AM_ICONV in ‘iconv.m4’

Integrating with Version Control Systems

* Distributed Development::     Avoiding version mismatch in distributed development
* Files under Version Control::  Files to put under version control
* PO Template File under Version Control??::  Put the POT File under Version Control?
* Translations under Version Control??::  Put PO Files under Version Control?
* autopoint Invocation::        Invoking the ‘autopoint’ Program
* po-fetch Invocation::         Invoking the ‘po-fetch’ Program

Other Programming Languages

* Language Implementors::       The Language Implementor's View
* Programmers for other Languages::  The Programmer's View
* Translators for other Languages::  The Translator's View
* Maintainers for other Languages::  The Maintainer's View
* List of Programming Languages::  Individual Programming Languages

The Translator's View

* c-format::                    C Format Strings
* objc-format::                 Objective C Format Strings
* c++-format::                  C++ Format Strings
* python-format::               Python Format Strings
* java-format::                 Java Format Strings
* csharp-format::               C# Format Strings
* javascript-format::           JavaScript Format Strings
* scheme-format::               Scheme Format Strings
* lisp-format::                 Lisp Format Strings
* elisp-format::                Emacs Lisp Format Strings
* librep-format::               librep Format Strings
* rust-format::                 Rust Format Strings
* go-format::                   Go Format Strings
* ruby-format::                 Ruby Format Strings
* sh-format::                   Shell Format Strings
* awk-format::                  awk Format Strings
* lua-format::                  Lua Format Strings
* object-pascal-format::        Object Pascal Format Strings
* modula2-format::              Modula-2 Format Strings
* d-format::                    D Format Strings
* ocaml-format::                OCaml Format Strings
* smalltalk-format::            Smalltalk Format Strings
* qt-format::                   Qt Format Strings
* qt-plural-format::            Qt Plural Format Strings
* kde-format::                  KDE Format Strings
* kde-kuit-format::             KUIT Format Strings
* boost-format::                Boost Format Strings
* tcl-format::                  Tcl Format Strings
* perl-format::                 Perl Format Strings
* php-format::                  PHP Format Strings
* gcc-internal-format::         GCC internal Format Strings
* gfc-internal-format::         GFC internal Format Strings
* ycp-format::                  YCP Format Strings

Individual Programming Languages

* C::                           C, C++, Objective C
* Python::                      Python
* Java::                        Java
* C#::                          C#
* JavaScript::                  JavaScript
* TypeScript::                  TypeScript
* Scheme::                      GNU guile - Scheme
* Common Lisp::                 GNU clisp - Common Lisp
* clisp C::                     GNU clisp C sources
* Emacs Lisp::                  Emacs Lisp
* librep::                      librep
* Rust::                        Rust
* Go::                          Go
* Ruby::                        Ruby
* sh::                          sh - Shell Script
* bash::                        bash - Bourne-Again Shell Script
* gawk::                        GNU awk
* Lua::                         Lua
* Pascal::                      Pascal - Free Pascal Compiler
* Modula-2::                    Modula-2
* OCaml::                       OCaml
* Smalltalk::                   GNU Smalltalk
* Vala::                        Vala
* wxWidgets::                   wxWidgets library
* Tcl::                         Tcl - Tk's scripting language
* Perl::                        Perl
* PHP::                         PHP Hypertext Preprocessor
* Pike::                        Pike
* GCC-source::                  GNU Compiler Collection sources
* YCP::                         YCP - YaST2 scripting language

sh - Shell Script

* sh - Three approaches::       Three approaches for Shell Scripts
* The gettext.sh approach::     The ‘gettext.sh’ approach
* The printf approach::         The ‘printf’ approach
* The printf_gettext approach:: The ‘printf_gettext’ approach
* Preparing for gettext.sh::    Preparing Shell Scripts for the ‘gettext.sh’ approach
* Preparing for printf::        Preparing Shell Scripts for the ‘printf’ approach
* Preparing for printf_gettext:: Preparing Shell Scripts for the ‘printf_gettext’ approach
* gettext Invocation::          Invoking the ‘gettext’ program
* ngettext Invocation::         Invoking the ‘ngettext’ program
* printf_gettext Invocation::   Invoking the ‘printf_gettext’ program
* printf_ngettext Invocation::  Invoking the ‘printf_ngettext’ program
* envsubst Invocation::         Invoking the ‘envsubst’ program
* eval_gettext Invocation::     Invoking the ‘eval_gettext’ function
* eval_ngettext Invocation::    Invoking the ‘eval_ngettext’ function
* eval_pgettext Invocation::    Invoking the ‘eval_pgettext’ function
* eval_npgettext Invocation::   Invoking the ‘eval_npgettext’ function

Perl

* General Problems::            General Problems Parsing Perl Code
* Default Keywords::            Which Keywords Will xgettext Look For?
* Special Keywords::            How to Extract Hash Keys
* Quote-like Expressions::      What are Strings And Quote-like Expressions?
* Interpolation I::             Unsupported String Interpolation
* Interpolation II::            Valid String Interpolation
* Parentheses::                 When To Use Parentheses
* Long Lines::                  How To Grok with Long Lines
* Perl Pitfalls::               Bugs, Pitfalls, and Things That Do Not Work

Other Data Formats

* Internationalizable Data::    Internationalizable Data Formats
* Localized Data::              Localized Data Formats

Internationalizable Data Formats

* POT::                         POT - Portable Object Template
* RST::                         Resource String Table
* Glade::                       Glade - GNOME user interface description
* GSettings::                   GSettings - GNOME user configuration schema
* AppData::                     AppData - freedesktop.org application description
* Preparing ITS Rules::         Preparing Rules for XML Internationalization

Preparing Rules for XML Internationalization

* ITS Rules::                   Specifying ITS Rules
* Locating Rules::              Specifying where to find the ITS Rules

Localized Data Formats

* Editable Message Catalogs::   Editable Message Catalogs
* Compiled Message Catalogs::   Compiled Message Catalogs
* Desktop Entry::               Desktop Entry files
* XML::                         XML files

Editable Message Catalogs

* PO::                          PO - Portable Object
* Java .properties::            Java .properties
* GNUstep .strings::            NeXTstep/GNUstep .strings

Compiled Message Catalogs

* MO::                          MO - Machine Object
* Java ResourceBundle::         Java ResourceBundle
* C# Satellite Assembly::       C# Satellite Assembly
* C# Resource::                 C# Resource
* Tcl message catalog::         Tcl message catalog
* Qt message catalog::          Qt message catalog

Concluding Remarks

* History::                     History of GNU ‘gettext’
* The original ABOUT-NLS::      Historical introduction
* References::                  Related Readings

Language Codes

* Usual Language Codes::        Two-letter ISO 639 language codes
* Rare Language Codes::         Three-letter ISO 639 language codes

Licenses

* GNU GPL::                     GNU General Public License
* GNU LGPL::                    GNU Lesser General Public License
* GNU FDL::                     GNU Free Documentation License