docs/development/internationalization.md

   1 # Internationalization
   2
   3 This page documents how internationalization works in Koha.
   4
   5 ## Making strings translatable
   6
   7 There are several ways of making a string translatable, depending on where it
   8 is located
   9
  10 ### In Template::Toolkit files (`*.tt`)
  11
  12 The simplest way to make a string translatable in a template is to do nothing.
  13 Templates are parsed as HTML files and almost all text nodes are considered as
  14 translatable strings. This also includes some attributes like `title` and
  15 `placeholder`.
  16
  17 This method has some downsides: you don't have full control over what would
  18 appear in PO files and you cannot use plural forms or context. In order to do
  19 that you have to use `i18n.inc`
  20
  21 `i18n.inc` contains several macros that, when used, make a string translatable.
  22 The first thing to do is to make these macros available by adding
  23
  24     [% PROCESS 'i18n.inc' %]
  25
  26 at the top of the template file. Then you can use those macros.
  27
  28 The simplest one is `t(msgid)`
  29
  30     [% t('This is a translatable string') %]
  31
  32 You can also use variable substitution with `tx(msgid, vars)`
  33
  34     [% tx('Hello, {name}', { name = 'World' }) %]
  35
  36 You can use plural forms with `tn(msgid, msgid_plural, count)`
  37
  38     [% tn('a child', 'several children', number_of_children) %]
  39
  40 You can add context, to help translators when a term is ambiguous, with
  41 `tp(msgctxt, msgid)`
  42
  43     [% tp('verb', 'order') %]
  44     [% tp('noun', 'order') %]
  45
  46 Or any combinations of the above
  47
  48     [% tnpx('bibliographic record', '{count} item', '{count} items', items_count, { count = items_count }) %]
  49
  50 ### In JavaScript files (`*.js`)
  51
  52 Like in templates, you have several functions available. Just replace `t` by `__`.
  53
  54     __('This is a translatable string');
  55     __npx('bibliographic record, '{count} item', '{count} items', items_count, { count: items_count });
  56
  57 ### In Perl files (`*.pl`, `*.pm`)
  58
  59 You will have to add
  60
  61     use Koha::I18N;
  62
  63 at the top of the file, and then the same functions as above will be available.
  64
  65     __('This is a translatable string');
  66     __npx('bibliographic record, '{count} item', '{count} items', $items_count, count => $items_count);
  67
  68 ### In installer and preferences YAML files (`*.yml`)
  69
  70 Nothing special to do here. All strings will be automatically translatable.
  71
  72 ## Manipulating PO files
  73
  74 Once strings have been made translatable in source files, they have to be
  75 extracted into PO files and uploaded on https://translate.koha-community.org/
  76 so they can be translated.
  77
  78 ### Install gulp first
  79
  80 The next sections rely on gulp. If it's not installed, run the following
  81 commands:
  82
  83     # as root
  84     npm install gulp-cli -g
  85
  86     # as normal user, from the root of Koha repository
  87     yarn
  88
  89 ### Create PO files for a new language
  90
  91 If you want to add translations for a new language, you have to create the
  92 missing PO files. You can do that by executing the following command:
  93
  94     # Replace xx-XX by your language tag
  95     gulp po:create --lang xx-XX
  96
  97 New PO files will be available in `misc/translator/po`.
  98
  99 ### Update PO files with new strings
 100
 101 When new features or bugfixes are added to Koha, new translatable strings can
 102 be added, other can be removed or modified, and the PO file become out of sync.
 103
 104 To be able to translate the new or modified strings, you have to update PO
 105 files. This can be done by executing the following command:
 106
 107     # Update PO files for all languages
 108     gulp po:update
 109
 110     # or only one language
 111     gulp po:update --lang xx-XX
 112
 113 ### Only extract strings
 114
 115 Creating or updating PO files automatically extract strings, but if for some
 116 reasons you want to only extract strings without touching PO files, you can run
 117 the following command:
 118
 119     gulp po:extract
 120
 121 POT files will be available in `misc/translator`.