Differential D25007 Diff 19 src/docs/contributor/internationalization.diviner

Changeset View

Standalone View

src/docs/contributor/internationalization.diviner

	@title Internationalization			@title Internationalization
	@group developer			@group developer

	Describes Phabricator translation and localization.			Describes Phorge translation and localization.

	Overview			Overview
	========			========

	Phabricator partially supports internationalization, but many of the tools			Phorge partially supports internationalization, but many of the tools
	are missing or in a prototype state.			are missing or in a prototype state.

	This document describes what tools exist today, how to add new translations,			This document describes what tools exist today, how to add new translations,
	and how to use the translation tools to make a codebase translatable.			and how to use the translation tools to make a codebase translatable.


	Adding a New Locale			Adding a New Locale
	===================			===================

	To add a new locale, subclass @{class:PhutilLocale}. This allows you to			To add a new locale, subclass @{class:PhutilLocale}. This allows you to
	introduce a new locale, like "German" or "Klingon".			introduce a new locale, like "German" or "Klingon".

	Once you've created a locale, applications can add translations for that			Once you've created a locale, applications can add translations for that
	locale.			locale.

	For instructions on adding new classes, see			For instructions on adding new classes, see
	@{article@phabcontrib:Adding New Classes}.			@{article@contrib:Adding New Classes}.


	Adding Translations to Locale			Adding Translations to Locale
	=============================			=============================

	To translate strings, subclass @{class:PhutilTranslation}. Translations need			To translate strings, subclass @{class:PhutilTranslation}. Translations need
	to belong to a locale: the locale defines an available language, and each			to belong to a locale: the locale defines an available language, and each
	translation subclass provides strings for it.			translation subclass provides strings for it.

	Translations are separated from locales so that third-party applications can			Translations are separated from locales so that third-party applications can
	provide translations into different locales without needing to define those			provide translations into different locales without needing to define those
	locales themselves.			locales themselves.

	For instructions on adding new classes, see			For instructions on adding new classes, see
	@{article@phabcontrib:Adding New Classes}.			@{article@contrib:Adding New Classes}.


	Writing Translatable Code			Writing Translatable Code
	=========================			=========================

	Strings are marked for translation with @{function@arcanist:pht}.			Strings are marked for translation with @{function@arcanist:pht}.

	The `pht()` function takes a string (and possibly some parameters) and returns			The `pht()` function takes a string (and possibly some parameters) and returns
	the translated version of that string in the current viewer's locale, if a			the translated version of that string in the current viewer's locale, if a
	translation is available.			translation is available.

	If text strings will ultimately be read by humans, they should essentially			If text strings will ultimately be read by humans, they should essentially
	always be wrapped in `pht()`. For example:			always be wrapped in `pht()`. For example:

	```lang=php			```lang=php
	$dialog->appendParagraph(pht('This is an example.'));			$dialog->appendParagraph(pht('This is an example.'));
	```			```

	This allows the code to return the correct Spanish or German or Russian			This allows the code to return the correct Spanish or German or Russian
	version of the text, if the viewer is using Phabricator in one of those			version of the text, if the viewer is using Phorge in one of those
	languages and a translation is available.			languages and a translation is available.

	Using `pht()` properly so that strings are translatable can be tricky. Briefly,			Using `pht()` properly so that strings are translatable can be tricky. Briefly,
	the major rules are:			the major rules are:

	- Only pass static strings as the first parameter to `pht()`.			- Only pass static strings as the first parameter to `pht()`.
	- Use parameters to create strings containing user names, object names, etc.			- Use parameters to create strings containing user names, object names, etc.
	- Translate full sentences, not sentence fragments.			- Translate full sentences, not sentence fragments.
	▲ Show 20 Lines • Show All 200 Lines • ▼ Show 20 Lines
	write the translation:			write the translation:

	```lang=php			```lang=php
	return pht('This will take %s hour(s).', new PhutilNumber($count));			return pht('This will take %s hour(s).', new PhutilNumber($count));
	```			```

	If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix			If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix
	this so the translation sounds better in English, provide translations for this			this so the translation sounds better in English, provide translations for this
	string in the @{class@phabricator:PhabricatorUSEnglishTranslation} file:			string in the @{class:PhabricatorUSEnglishTranslation} file:

	```lang=php			```lang=php
	'This will take %s hour(s).' => array(			'This will take %s hour(s).' => array(
	'This will take an hour.',			'This will take an hour.',
	'This will take hours.',			'This will take hours.',
	),			),
	```			```

	▲ Show 20 Lines • Show All 86 Lines • ▼ Show 20 Lines


	Next Steps			Next Steps
	==========			==========

	Continue by:			Continue by:

	- adding a new locale or translation file with			- adding a new locale or translation file with
	@{article@phabcontrib:Adding New Classes}.			@{article@contrib:Adding New Classes}.