Document internationalization

Test Plan: Generated docs.

Reviewers: epriestley

Reviewed By: epriestley

CC: aran, Korvin

Maniphest Tasks: T1139

Differential Revision: https://secure.phabricator.com/D2779

src/docs/contributing/internationalization.diviner

@@ -0,0 +1,61 @@
+@title Internationalization
+@group contrib
+
+What is required from developers to get Phabricator translatable.
+
+= API =
+
+Translator API is provided by libphutil. It gives us `PhutilTranslator` class
+and global `pht()` function built on top of it.
+
+Developers are supposed to call `pht()` on all strings that require translation.
+
+Phabricator provides translations for this translator through
+@{class:PhabricatorTranslation} class.
+
+= Adding a New Translation =
+
+Adding a translation which uses the same language rules as some already existing
+translation is relatively simple: Just extend @{class:PhabricatorTranslation}
+and you will be able to specify this class in the global configuration
+'translation.provider' and users will be able to select it in their preferences.
+
+= Adding a New Language =
+
+Adding a language involves all steps as adding a translation plus specifying the
+language rules in `PhutilTranslator::chooseVariant()`.
+
+= Singular and Plural =
+
+Different languages have various rules for using singular and plural. All you
+need to do is to call `pht()` with a text that is suitable for both forms.
+Example:
+
+  pht('%d beer(s)', $count);
+
+Translators will translate this text for all different forms the language uses:
+
+  // English translation
+  array('%d beer', '%d beers');
+
+  // Czech translation
+  array('%d pivo', '%d piva', '%d piv');
+
+The ugly identifier passed to `pht()` will remain in the text only if the
+translation doesn't exist.
+
+= Male and Female =
+
+Different languages use different words for talking about males, females and
+unknown genders. Callsites have to call `pht()` passing @{class:PhabricatorUser}
+(or other implementation of `PhutilPerson`) if talking about the user. Example:
+
+  pht('%s wrote', $actor);
+
+Translators will create this translations:
+
+  // English translation
+  '%s wrote';
+
+  // Czech translation
+  array('%s napsal', '%s napsala');