Gettext snadno a rychle

20. 1. 2010 | Daniel Kolesa | Návody | 9575×

Už jste někdy jako programátor potřebovali přeložit svou aplikaci nebo jako překladatel vytvářet nové překlady a nevěděli „jak na to“? Tímto návodem se pokusím věc trochu objasnit a vysvětlit „vše“, co byste jako programátor nebo překladatel měli znát.

Obsah

• Co je to GNU Gettext?
• Jaké jazyky mohu použít s GNU Gettext?
• 1. Vývojářská část
  • Píšeme zdrojový kód
  • Připravujeme zdrojový kód
  • Testujeme
  • A. Samostatný zdrojový kód a vlastní Makefile
  • B. Použití s autotools
• 2. Překladatelská část
  • A. Vytváříme nový překlad
  • B. Upravujeme překlad
  • C. Program používá jiný systém pro instalaci
  • Programy, které byste měli znát
• 3. Užitečné odkazy, závěr

Co je to GNU Gettext?

GNU Gettext je sada nástrojů poskytující framework pro vytváření vícejazyčných aplikací. Překlady jsou uloženy v tzv. katalozích, které mají formát .po a pro použití aplikací se překládají do binárního formátu .mo, který není závislý na systému, popř. architektuře procesoru. Šablony, ze kterých se vytváří soubory .po, mají příponu .pot.

Nejspíše se setkáte také se zkratkami l10n a i18n – první je „localization“ – to je samotný překlad a druhá je „internationalization“ – příprava vašeho programu k l10n. Čísla označují počet znaků ve slovu mezi prvním a posledním písmenem.

Jaké jazyky mohu použít s GNU Gettext?

Gettext má tzv. „bindings“ pro velký počet jazyků:

• C (C, C++, Objective C)
• Python
• Perl
• Lisp
• Bash (popř. sh)
• PHP
• Java
• a další.

Gettext samotný je napsaný v C. Návod se bude zabývat použitím s jazykem C.

1. Vývojářská část

Při použití s jazykem C můžete využít dvě metody pro podporu překladů: pomocí Autotools (doporučuji), nebo přímo na zdrojový kód C. Použití s autotools je mnohem univerzálnější a často i jednodušší díky podpůrným nástrojům jako autopoint.

V obou případech budeme překládat jednoduchý zdrojový kód:

#include <stdio.h>
#include <limits.h>
#include <string.h>

static void print_help(int argc, char **argv);
static void print_help(int argc, char **argv)
{
   printf("--- Gettext testing app help information ---\n");
   printf("   USAGE: %s [argument]\n", argv[0]);
   printf("     Possible arguments:\n       blah: print some message\n       foo: print another message\n");
}

int main(int argc, char **argv)
{
   if (argc != 1)
     {
    if (!strcmp(argv[1], "blah"))
      printf("Some message to be translated.\nThis is a new line.\nAnother new line to make the message long.\n");
    else if (!strcmp(argv[1], "foo"))
      printf("Another message to be translated.\n\n\nSome newline after empty lines.\n\tMessage after a tab.\n");
    else
      printf("Translatable error – unsupported argument provided.\n");
     }
   else
     {
    printf("Translatable error – no arguments provided. Printing help.\n");
    print_help(argc, argv);
     }

   return 0;
}

Píšeme zdrojový kód

Při práci s gettextem je dobré dodržovat pár základních pravidel, která usnadňují další překlad.

1. Nedělte vypisovaní textu (třeba pomocí printf) – používejte místo toho znaky \n,\t atd. tzn. místo

   printf("first line\n");
   printf("second line\n");
   

   napište

   printf("first line\nsecond line\n");

2. Používejte co nejvíce argumenty pro printf, snprintf. Věci, které nemají být přeloženy, si ukládejte zvlášť, tzn. místo

   if (!strcmp(myvar, "blah"))
      printf("value of myvar is: blah");
   else if (!strcmp(myvar, "foo"))
      printf("value of myvar is: foo");
   else
      printf("value of myvar is: unknown");
   

   použijte raději

   if (!strcmp(myvar, "blah") || !strcmp(myvar, "foo"))
      printf("value of myvar is %s", myvar);
   else
      printf("value of myvar is: unknown");
   

3. Nezoznačujte interní řetězce programu k překladu.

4. Gettext inicializujte ve funkci main() vašeho programu a jeho definice zapisujte do hlavičkového souboru, pokud váš program nějaký má.

Připravujeme zdrojový kód

Před začátkem psaní Makefile, popř. použití autotools je nutné nejprve zdrojový kód připravit a označit řetězce k překladu.

Nejdříve přidáme nějaké inklůdy na začátek.

#include <locale.h>
#include <libintl.h>

• locale.h hlavička je potřeba vždy, jak při využití vlastního Makefile, tak při použití autotools.
• libintl.h v případě autotools není potřeba (zato je ale třeba inklůdovat config.h).

Dále si musíme nadefinovat funkci k označení překladu:

#define _(string) gettext(string)

Ta je vcelku volitelná, nicméně psát pokaždé gettext() je zdlouhavé a _() se používá nejčastěji. Také ovlivňuje parametry --keywords v xgettext. Kromě funkce gettext() by vás mohly zajímat ještě dgettext a ngettext:

1. dgettext – chová se stejně jako gettext(), ale musíte poskytnout dva argumenty – druhý je tzv. domainname – většinou název vaší aplikace a název .mo souboru. Definuje se takto:

   #define D_(domain, string) dgettext(domain, string)

2. ngettext – umožňuje specifikovat plurální formy určitého řetězce. Potřebuje tři argumenty a definuje se takto:

   #define N_(string1, string2, n) ngettext(string1, string2, n)

   A jeho použití:

   printf(ngettext("%d file found.", "%d files found", num), num);

3. num je typu int a pokud je jeho hodnota 1, vypíše se první řetězec, jinak se vypíše druhý.

4. Dále ještě existuje dngettext, který funguje podobně jako gettext vs dgettext.

   #define DN_(domain, string1, string2, n) dngettext(domain,
   string1,
   string2, n)

Nyní se vraťme zpět k programu. Po definici _() můžete označit veškeré řetězce k překladu takhle:

printf(_("   USAGE: %s [argument]\n"), argv[0]);

Docílíte tím toho, že pokud gettext při spuštění programu najde katalog a přeložený řetězec, použije jej místo toho původního.

Po označení všech řetězců už stačí jen gettext inicializovat na začátku funkce main():

setlocale(LC_ALL, "");
bindtextdomain("gettexttest", "/usr/share/locale");
textdomain("gettexttest");

První řádek je určen ke zjištění lokalizace prostředí (zkuste si vypsat printf(setlocale(LC_ALL, ""));), dále se nastavuje domainname, o kterém jsem se zmiňoval už předtím. Druhý argument k bindtextdomain určuje, kde hledat složku LC_MESSAGES obsahující přeložené .mo soubory.

Tím máme základ hotov, váš připravený kód by měl vypadat takhle:

#include <stdio.h>
#include <limits.h>
#include <string.h>
#include <locale.h>
#include <libintl.h>
#define _(string) gettext(string)

static void print_help(int argc, char **argv);

static void print_help(int argc, char **argv)
{
   printf(_("--- Gettext testing app help information ---\n"));
   printf(_("   USAGE: %s [argument]\n"), argv[0]);
   printf(_("     Possible arguments:\n       blah: print some message\n       foo: print another message\n"));
}

int main(int argc, char **argv)
{
   setlocale(LC_ALL, "");
   bindtextdomain("gettexttest", "/usr/share/locale");
   textdomain("gettexttest");
   if (argc != 1)
     {
    if (!strcmp(argv[1], "blah"))
      printf(_("Some message to be translated.\nThis is a new line.\nAnother new line to make the message long.\n"));
    else if (!strcmp(argv[1], "foo"))
      printf(_("Another message to be translated.\n\n\nSome newline after empty lines.\n\tMessage after a tab.\n"));
    else
      printf(_("Translatable error – unsupported argument provided.\n"));
     }
   else
     {
    printf(_("Translatable error – no arguments provided. Printing help.\n"));
    print_help(argc, argv);
     }

   return 0;
}

Testujeme

Kód si uložte do nějaké prázdné složky pod názvem gettexttest.c. Pak stačí nainstalovat balíčky gettext a gettext-base (na Debianu/Ubuntu, na jiných distribucích se může lišit), pokud je ještě nemáte, a standardním způsobem program přeložit:

gcc gettexttest.c -o gettexttest

Po spuštění ./gettexttest by se mělo vše správně vypsat – bez překladu. Pro zprovoznění překladu musíte vytahat řetězce ven z programu do .pot souboru. K tomu slouží program xgettext, pusťte tedy:

xgettext --keyword=_ gettexttest.c -o gettexttest.pot

Paremetr --keyword určuje, jaký prefix funkcí se použije: tzn. --keyword=_ bude hledat _(). Po spuštění příkazu by se měl vytvořit ve složce soubor gettexttest.pot. Otevřte si ho v textovém editoru a uvidíte:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2009-11-17 20:54+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

První řádky začínající na # jsou komentáře, tam si napište nějaký popis a vaši e-mailovou adresu. V Project-Id-Version si vyplňte třeba název vašeho programu. Další řádek je e-mailová adresa pro hlášení bugů, další řádky nechte. Poslední řádek, který by vás mohl zajímat, je Language-Team: – tam dopište cs <váš_e-mail>.

Soubor uložte jako gettexttest.po a nepokoušejte se jej překládat.

Nyní si nainstalujte program POedit, pokud chcete program pro Gtk+, nebo KBabel či Lokalize, což jsou programy pro KDE.

Tyto programy slouží k překladu .po souborů. Já používám POEdit. Po spuštění programu budete nejspíš vyzváni k vyplnění e-mailové adresy a dalších informací. Vyplňte je, budou se ukládat do .po souborů. Teď si v POEditu otevřete váš gettextest.po. Ovládání je intuitivní – nahoře je toolbar, pak seznam řetězců k překladu. Pro přeložení řetězce na něj stačí kliknout, zkopírovat obsah horního pole, vložit do spodního a přeložit. Uložením si POEdit sám generuje .mo soubor. Pokud chcete vytvořit .mo ručně, tak použijte program msgfmt:

msgfmt gettexttest.po -o gettexttest.mo

O dalších nástrojích se dále rozepíšu v překladatelské sekci. Měli byste ale systém překladů znát.

Až budete mít .mo soubor, zkopírujte jej jako root do /usr/share/locale/cs/LC_MESSAGES/ (/usr/share/locale jste zadávali v bindtextdomain, název gettexttest.mo v bindtextdomain a textdomain, cs je kód země)

Teď si zkuste pustit váš program a uvidíte, že je přeložen :)

A. Samostatný zdrojový kód a vlastní Makefile

V tomto případě záleží pouze na tom, jak si systém vymyslíte – důležité je to navrhnout tak, aby nebyl problém s více jazyky. Já udělal něco takového:

APP=gettexttest
SOURCE=gettexttest.c
PREFIX=/usr
LANGUAGES=cs

all: po build

build: $(SOURCE)
    if test ! -f $(APP); then gcc $(SOURCE) -o $(APP); fi

install: build install-po
    /usr/bin/install -m 755 $(APP) $(PREFIX)/bin/

pot: $(SOURCE)
    xgettext --keyword=_ $(SOURCE) -o $(APP).pot

po:
    for x in $(LANGUAGES) ; do \
        if test -f $$x.po; then msgfmt $$x.po -o $$x.mo; fi ; \
    done

install-po: po
    for x in $(LANGUAGES) ; do \
        if test -f $$x.mo; then /usr/bin/install -m 644 $$x.mo /usr/share/locale/cs/LC_MESSAGES/$(APP).mo; fi ; \
    done

clean:
    if test -f $(APP); then rm $(APP); fi
    if test $(shell ls *.mo); then rm *.mo; fi

distclean: clean
    if test $(shell ls *.pot); then rm *.pot; fi

B. Použití s autotools

Zde je situace podle mě jednodušší. V rootu vašeho programu (tzn. tam, kde se nachází soubor configure.ac) si vytvořte složku s názvem po. Přepněte se do ní, vytvořte tam soubor Makevars a vložte do něj:

DOMAIN = $(PACKAGE)
subdir = po
top_builddir = ..
XGETTEXT_OPTIONS = --keyword=_ --keyword=N_ --from-code=UTF-8
--foreign-user
COPYRIGHT_HOLDER = your developer team or you
MSGID_BUGS_ADDRESS = your@email.com
EXTRA_LOCALE_CATEGORIES =

Tím specifikujete parametry pro xgettext atd.

Dále potřebujete soubor POTFILES.in. V něm jsou napsány soubory, které se mají použít jako zdroj pro xgettext. V POTFILES.in jednoho z mých projektů například je:

src/bin/about.c
src/bin/conf.c
src/bin/plugin.c
src/bin/stickies.c
src/bin/config_gui.c

Tzn. zapíšete na každý řádek nový soubor tak, že výchozí adresář je root adresář vašeho projektu.

Posledním potřebným souborem je LINGUAS. V něm jsou zapsány všechny jazyky, které jsou přeloženy. Tzn. něco jako:

cs fr it

Nezapisujte do něj nepřeložené jazyky.

O zbytek se postará pomocný nástroj autopoint.

Dále je nutné upravit váš configure.ac popř. configure.in. Vložte do něj:

if test "x${prefix}" = "xNONE"; then
  AC_DEFINE_UNQUOTED(PACKAGE_LOCALE_DIR, "${ac_default_prefix}/share/locale", [Locale-specific data directory])
else
  AC_DEFINE_UNQUOTED(PACKAGE_LOCALE_DIR, "${prefix}/share/locale", [Locale-specific data directory])
fi

AM_GNU_GETTEXT([external])
AM_GNU_GETTEXT_VERSION([0.12.1])

Často se hodí definovat věcí více:

if test "x${prefix}" = "xNONE"; then
  AC_DEFINE_UNQUOTED(PACKAGE_LOCALE_DIR, "${ac_default_prefix}/share/locale", [Locale-specific data directory])
else
  AC_DEFINE_UNQUOTED(PACKAGE_LOCALE_DIR, "${prefix}/share/locale", [Locale-specific data directory])
fi

if test "x${prefix}" = "xNONE"; then
  AC_DEFINE_UNQUOTED(PACKAGE_DATA_DIR, "${ac_default_prefix}/share/${PACKAGE}", [Shared Data Directory])
else
  AC_DEFINE_UNQUOTED(PACKAGE_DATA_DIR, "${prefix}/share/${PACKAGE}", [Shared Data Directory])
fi

if test "x${datadir}" = 'x${prefix}/bin'; then
  if test "x${prefix}" = "xNONE"; then
    AC_DEFINE_UNQUOTED(PACKAGE_BIN_DIR, "${ac_default_prefix}/bin", [Installation directory for user executables])
  else
    AC_DEFINE_UNQUOTED(PACKAGE_BIN_DIR, "${prefix}/bin", [Installation directory for user executables])
  fi
else
  AC_DEFINE_UNQUOTED(PACKAGE_BIN_DIR, "${bindir}", [Installation directory for user executables])
fi

packagesrcdir=`cd $srcdir && pwd`
AC_DEFINE_UNQUOTED(PACKAGE_SOURCE_DIR, "${packagesrcdir}", [Source code directory])

AM_GNU_GETTEXT([external])
AM_GNU_GETTEXT_VERSION([0.12.1])

Podle toho, jestli váš projekt využívá BINDIR, nebo DATADIR. Tyto řádky vložte třeba před PKG_CHECK_MODULES.

Nakonec vložte jako jednu z položek AC_OUTPUT:

po/Makefile.in

Pak si otevřete hlavní Makefile.am a pokud tam máte třeba:

SUBDIRS = src data

tak upravte na:

SUBDIRS = src data po

Pokud proměnnou nemáte, vytvořte ji jako:

SUBDIRS = po

Tím by byly úpravy autotools hotové. Teď bude potřeba provést pár úprav do zdrojáku.

Nejdříve upravte:

#include <locale.h>
#include <libintl.h>
#define _(string) gettext(string)

na

#include <locale.h>
#include "config.h";
#define _(string) gettext(string)

Dále je dobré kvůli definici PACKAGE_LOCALE_DIR nenastavovat napevno /usr/share/locale a gettexttest nenastavovat v kódu, ale z configure.ac, takže upravte:

setlocale(LC_ALL, "");
bindtextdomain("gettexttest", "/usr/share/locale");
textdomain("gettexttest");

na

setlocale(LC_ALL, "");
bindtextdomain(PACKAGE, PACKAGE_LOCALE_DIR);
textdomain(PACKAGE);

PACKAGE definuje AC_INIT, takže pokud vypadá takto:

AC_INIT([gettexttest], [0.1], [quaker66@gmail.com])

tak se PACKAGE automaticky nahradí za gettexttest. Makefile ze složky po se postará o automatické přejmenování a instalaci .mo souborů podle proměnné PACKAGE.

Soubor si uložte a můžete přejít k poslední části, a tou je úprava autogen.sh (pokud používáte) nebo spuštění autopoint.

Skript autogen.sh nejspíš používáte, pokud je váš program někde v SVN. S podporou překladu vypadá takto (některé části mohou ve vašem projektu chybět):

#!/bin/sh

rm -rf autom4te.cache
rm -f aclocal.m4 ltmain.sh

touch README
touch ABOUT-NLS

echo "Running autopoint…" ; autopoint -f || :
echo "Running aclocal…" ; aclocal -I m4 $ACLOCAL_FLAGS || exit 1
echo "Running autoconf…" ; autoconf || exit 1
echo "Running autoheader…" ; autoheader || exit 1
echo "Running libtoolize…" ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1
echo "Running automake…" ; automake --add-missing --copy --gnu ||
exit 1

if [ -z "$NOCONFIGURE" ]; then
    ./configure "$@"
fi

Pro ty, kdo jej nepoužívají: Je to skript, který spustí jednotlivé části autotools tak, aby se vygeneroval skript configure z configure.ac. Pro překlad je důležitý řádek

echo "Running autopoint…" ; autopoint -f || :

Autopoint je pomocný program z balíku gettext, který sám do složky po zkopíruje veškeré důležité soubory jako Makefile.in.in. Pokud autogen nepoužíváte, pusťte jej samostatně:

autopoint -f

Nyní je podpora překladu hotova. Můžete pustit:

./autogen.sh

Nebo, pokud jste autopoint pustili zvlášť, a váš program bude správně manipulovat se složkou po a instalovat překlady:

./configure

Pokračování: Návod pro překladatele

       

Komentáře

[Jan Drábek]

Možná by chtělo ještě zdůraznit, že článek má i druhou část, takhle je to vcelku nešikovně "schované".

Btw. Velice prakticky napsaný článek

[CET]

Soubor uložte jako gettexttest.po a nepokoušejte se jej překládat.

Proc ne??? Ja to vzdycky otevren ve vimu a prekladal jsem. Co je na tom za problem?

[----]

no, editory určené k tomuto účelu jako poedit při překladu taky zapisují správné informace o kódování v hlavičce - je to jistější že se ti to kódování nerozhodí :)

ale když soubor máš už částečně přeložený třeba tak můžeš něco dopřekládat i ve vimu

[petr_p]

Nejenom kódování, ale také jméno posledního překladatele, časovou značku poslední úpravy překladu.

Na druhou stranu musím říct, že já mám univerzální Makefile, který tohle (a spoustu jiných věcí jako odeslání překladu robotovi) za mě dělá a používám taky vim. Grafické nástroje mě neoslovili (asi protože mám zkušenost jen s příšerným linguistem).

[----]

jasně ;)

v tvém případě bych radši použil autotools, který udělá vše za tebe

[Makefile]

Nechces se o ten svuj Makefile podelit?

[disorder]

pekne. este sa v pythone pouziva aj pybabel, napr.:

pybabel extract -F babel.cfg -o app.pot app
pybabel update -i app.pot -d . -D app -l sk

[leko]

Super clanok, pekne podrobne popisany.

Pri odporucani na kde/qt prekladatelsky program by som neoporucal uz kbabel, ten je zastaraly, asi by tam mal byt spomenuty len lokalize. Ten je najlepsi najma pri preklade vacsich projektov. Ma funkcie bez, ktorych sa tazko preklada (translation memory, slovnik, inteligentne vkladanie tagov, kontrola pravopisu na cely .po apod.)

[Andrej Herceg]

Kbabel je zastaralý možno pre používateľov KDE4 (KDE 4, KDE SC 4...). ;) Kbabel podporuje všetko, okrem toho inteligentného vkladania tagov (teda aspoň si myslím, nič špeciálne s tagmi som nikdy nepotreboval robiť).

[belisarivs]

Kbabel zatim umi oproti Lokalize navic kontrolu syntaxe. Ale to jde provadet skripty (pology), ktere pak otevrou syntakticky nespravne retezce primo v Lokalize.

[petr_p]

Gettext umí podle klíčových slov hlídat syntaxi mezi msgid a msgstr. Například printf(3) escapovací sekvence:

#: ../src/aosd/aosd_ui.c:242
#, c-format
msgid "monitor %i"
msgstr "monitoru %i"

Nevíte, jestli lze ve zdrojovém kódu vyznačit, že daný řetězec není formátovací printf řetězec?

V jednom programu je použito něco jako _("100% during") a xgettext takovému msgid přidává příznak c-format, což je samozřejmě špatně. Kontrolní mechanismy pak křičí, že v překladu nesedí formátovací sekvence kolem procentítka. A mně nebaví opakovaně odmazávat příznak c-format.

Čekal bych, že gettext něco takového bude umět, protože zrovna tak umí extrahovat kontextové komentáře zdrojového kódu ohledně překladu (často se používá na upozornění překladatelů programátorem, že určité slovo v hlášce je lexikál nebo vlastní jméno).

[----]

bych to vyescapoval..

_("100\% during")

[Andrej Herceg]

Skús /* xgettext:no-c-format */

[petr_p]

To je ono. Dík.

[Josef Kufner]

Btw, nevíte o nějakém způsobu, jak v PHP konvertovat .po na .mo, když nemůžu spustit msgfmt?

[----]

jako přímo z tvého PHP skriptu nějak?

[Josef Kufner]

Jo, jo. Mám udělaný v PHP instalátor, který si stáhne zip z repositáře a nainstaluje celou aplikaci (také PHP), zkontroluje nastavení a povytváří všecko co potřebuje, ale na serveru je zakázané exec(), takže je problém s překlady a graphvizem …

[----]

to asi nepůjde.. budeš si muset nechat povolit spuštění msgfmt.

[Josef Kufner]

Asi budu muset najít nějakou jinou cestu. Já jen jestli třeba nědo neví o implementaci msgfmt v php nebo něco takového

[Jan Drábek]

Lokálně? (Má smysl dělat něco podobného na serveru, když vlákna Apache/PHP stejně drží do umření starou verzi?)

[EVRAMP]

Děkuji za článek.