[Summary view] [Print] [Text view]

   1  @title Internationalization
   2  @group developer
   3  
   4  What is required from developers to get Phabricator translatable.
   5  
   6  = API =
   7  
   8  Translator API is provided by libphutil. It gives us
   9  @{class@libphutil:PhutilTranslator} class and global @{function@libphutil:pht}
  10  function built on top of it.
  11  
  12  Developers are supposed to call @{function@libphutil:pht} on all strings that
  13  require translation.
  14  
  15  Phabricator provides translations for this translator through
  16  @{class:PhabricatorTranslation} class.
  17  
  18  = Adding a New Translation =
  19  
  20  Adding a translation which uses the same language rules as some already existing
  21  translation is relatively simple: Just extend @{class:PhabricatorTranslation}
  22  and you will be able to specify this class in the global configuration
  23  'translation.provider' and users will be able to select it in their preferences.
  24  
  25  = Adding a New Language =
  26  
  27  Adding a language involves all steps as adding a translation plus specifying the
  28  language rules in @{method@libphutil:PhutilTranslator::chooseVariant}.
  29  
  30  = Singular and Plural =
  31  
  32  Different languages have various rules for using singular and plural. All you
  33  need to do is to call @{function@libphutil:pht} with a text that is suitable for
  34  both forms. Example:
  35  
  36    pht('%d beer(s)', $count);
  37  
  38  Translators will translate this text for all different forms the language uses:
  39  
  40    // English translation
  41    array('%d beer', '%d beers');
  42  
  43    // Czech translation
  44    array('%d pivo', '%d piva', '%d piv');
  45  
  46  The ugly identifier passed to @{function@libphutil:pht} will remain in the text
  47  only if the translation doesn't exist.
  48  
  49  = Male and Female =
  50  
  51  Different languages use different words for talking about males, females and
  52  unknown genders. Callsites have to call @{function@libphutil:pht} passing
  53  @{class:PhabricatorUser} (or other implementation of
  54  @{interface@libphutil:PhutilPerson}) if talking about the user. Example:
  55  
  56    pht('%s wrote', $actor);
  57  
  58  Translators will create this translations:
  59  
  60    // English translation
  61    '%s wrote';
  62  
  63    // Czech translation
  64    array('%s napsal', '%s napsala');