开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

PHP-I18N

Internationalization and localization for PHP

Provide your application in multiple languages, to users in various countries, with different formats and conventions.

Requirements

• PHP 5.6.0+
  • GNU gettext extension (gettext)
  • Internationalization extension (intl)

Note: On Windows, you may have to use the non-thread-safe (NTS) version of PHP.

Installation

1. Include the library via Composer [?]:

   $ composer require delight-im/i18n

2. Include the Composer autoloader:

   require __DIR__ . '/vendor/autoload.php';

Usage

• What is a locale?
• Decide on your initial set of supported locales
• Creating a new instance
• Directory and file names for translation files
• Activating the correct locale for the user
  • Automatically
  • Manually
• Enabling aliases for translation
• Identifying, marking and formatting translatable strings
  • Basic strings
  • Strings with formatting
  • Strings with extended formatting
  • Singular and plural forms
  • Singular and plural forms with formatting
  • Singular and plural forms with extended formatting
  • Strings with context
  • Strings marked for later translation
• Extracting and updating translatable strings
• Translating the extracted strings
• Exporting translations to binary format
• Retrieving the active locale
• Information about locales
  • Names of locales in the current language
  • Native names of locales
  • English names of locales
  • Names of languages in the current language
  • Native names of languages
  • English names of languages
  • Names of scripts in the current language
  • Native names of scripts
  • English names of scripts
  • Names of regions in the current language
  • Native names of regions
  • English names of regions
  • Language codes
  • Script codes
  • Region codes
  • Directionality of text
• Controlling the leniency for lookups and comparisons of locales

What is a locale?

Put simply, a locale is a set of user preferences and expectations, shared across larger communities in the world, and varying by geographic region. Notably, this includes a user’s language and their expectation of how numbers, dates and times are to be formatted.

Decide on your initial set of supported locales

Whatever set of languages, scripts and regions you decide to support at the beginning, you will be able to add or remove locales at any later time. So perhaps you might like to start with just 1–3 locales to get started faster.

You can find a list of various locale codes in the Codes class and use the corresponding constants to refer to the locales, which is the recommended solution. Alternatively, you may copy their string values, which use a subset of IETF BCP 47 (RFC 5646) or Unicode CLDR identifiers.

Prior to using your initial set of languages, you should ensure they’re installed on any machine you’d like to develop or deploy your application on, making sure they are known to the operating system:

$ locale -a

If a certain locale is not installed yet, you can add it like the es-AR locale in the following example:

$ sudo locale-gen es_AR
$ sudo locale-gen es_AR.UTF-8
$ sudo update-locale
$ sudo service apache2 restart

Note: On Unix-like operating systems, the locale codes used during installation must use underscores.

Creating a new instance

In order to create an instance of the I18n class, just provide your set of supported locales. The only special entry is the very first locale, which also serves as the default locale if no better match can be found for the user.

$i18n = new \Delight\I18n\I18n([
    \Delight\I18n\Codes::EN_US,
    \Delight\I18n\Codes::DA_DK,
    \Delight\I18n\Codes::ES,
    \Delight\I18n\Codes::ES_AR,
    \Delight\I18n\Codes::KO,
    \Delight\I18n\Codes::KO_KR,
    \Delight\I18n\Codes::RU_RU,
    \Delight\I18n\Codes::SW
]);

Directory and file names for translation files

Your translation files will later have to be stored in the following location:

locale/<LOCALE_CODE>/LC_MESSAGES/messages.po

That may be, for example, using the es-ES locale:

locale/es_ES/LC_MESSAGES/messages.po

If you need to change the path to the locale directory or want to use a different name for that directory, just specify its path explicitly:

$i18n->setDirectory(__DIR__ . '/../translations');

The filename in the LC_MESSAGES directory, i.e. messages.po, is the name of the application module with the extension for PO (Portable Object) files. There’s usually no need to change that, but if you still want to do that, simply call the following method:

$i18n->setModule('messages');

Note: On Unix-like operating systems, the locale codes used in the directory names have to use underscores, whereas on Windows, the codes have to use hyphens.

Activating the correct locale for the user

Automatically

The easiest way to pick the most suitable locale for the user is to let this library decide based on various signals and options automatically:

$i18n->setLocaleAutomatically();

This will check and decide based on the following factors (in that order):

1. Subdomain with locale code (e.g. da-DK.example.com)

   (Note: Locale codes in the (leftmost) subdomain are case-insensitive, i.e. da-dk works as well, and you can leave out region or script names, i.e. merely da would be sufficient here.)

2. Path prefix with locale code (e.g. http://www.example.com/pt-BR/welcome.html)

   (Note: Locale codes in the path prefix are case-insensitive, i.e. pt-br works as well, and you can leave out region or script names, i.e. merely pt would be sufficient here.)

3. Query string with locale code

   1. the locale parameter
   2. the language parameter
   3. the lang parameter
   4. the lc parameter

4. Session field defined via I18n#setSessionField (e.g. $i18n->setSessionField('locale');)

5. Cookie defined via I18n#setCookieName (e.g. $i18n->setCookieName('lc');), with an optional lifetime defined via I18n#setCookieLifetime (e.g. $i18n->setCookieLifetime(60 * 60 * 24);), where a value of null means that the cookie is to expire at the end of the current browser session

6. HTTP request header Accept-Language (e.g. en-US,en;q=0.5)

You will usually choose a single one of these options to store and transport your locale codes, with other factors (specifically the last one) as fallback options. The first three options (and the last one) may provide advantages in terms of search engine optimization (SEO) and caching.

Manually

Of course, you can also specify the locale for your users manually:

try {
    $i18n->setLocaleManually('es-AR');
}
catch (\Delight\I18n\Throwable\LocaleNotSupportedException $e) {
    die('The locale requested by the user is not supported');
}

Enabling aliases for translation

Set up the following aliases in your application code to simplify your work with this library, to make your code more readable, and to enable support for the included tooling and other GNU gettext utilities:

function _f($text, ...$replacements) { global $i18n; return $i18n->translateFormatted($text, ...$replacements); }

function _fe($text, ...$replacements) { global $i18n; return $i18n->translateFormattedExtended($text, ...$replacements); }

function _p($text, $alternative, $count) { global $i18n; return $i18n->translatePlural($text, $alternative, $count); }

function _pf($text, $alternative, $count, ...$replacements) { global $i18n; return $i18n->translatePluralFormatted($text, $alternative, $count, ...$replacements); }

function _pfe($text, $alternative, $count, ...$replacements) { global $i18n; return $i18n->translatePluralFormattedExtended($text, $alternative, $count, ...$replacements); }

function _c($text, $context) { global $i18n; return $i18n->translateWithContext($text, $context); }

function _m($text) { global $i18n; return $i18n->markForTranslation($text); }

If the variable holding your global I18n instance is not named $i18n, you have to adjust each occurrence of $i18n in the snippet above accordingly, of course.

Identifying, marking and formatting translatable strings

In order to internationalize your code base, you have to identify and mark strings that can be translated, and use formatting with more complex strings. Afterwards, these marked strings can be extracted automatically, to be translated outside of the actual code, and will be inserted again during runtime by this library.

In general, you should follow these simple rules when marking strings for translations:

• Use units of text as large as possible. This could be a single word (e.g. “Save” on a button), several words (e.g. “Create a new account” in a headline), or full sentences (e.g. “Your account has been created.”).
• Strive to treat entire sentences as atomic units whenever possible, and don’t compose sentences from multiple translated words or parts unless absolutely necessary.
• Use string formatting via one of the dedicated functions and methods instead of resorting to string concatenation or string interpolation.
• Handle singular and plural forms using the dedicated functions and methods, which work even for languages with complex plural rules, which are not always as simple as the binary English rule.

Basic strings

Wrap the sentences, phrases and labels of your user interface inside of the _ function:

_('Welcome to our online store!');
// Welcome to our online store!

_('Create account');
// Create account

_('You have been successfully logged out.');
// You have been successfully logged out.

Strings with formatting

Wrap the sentences, phrases and labels of your user interface inside of the _f function:

_f('This is %1$s.', 'Bob');
// This is Bob.

_f('This is %1$d.', 3);
// This is 3.

_f('This is %1$05d.', 3);
// This is 00003.

_f('This is %1$ 5d.', 3);
// This is     3.
// This is ␣␣␣␣3.

_f('This is %1$+d.', 3);
// This is +3.

_f('This is %1$+06d.', 3);
// This is +00003.

_f('This is %1$+ 6d.', 3);
// This is     +3.
// This is ␣␣␣␣+3.

_f('This is %1$f.', 3.14);
// This is 3.140000.

_f('This is %1$012f.', 3.14);
// This is 00003.140000.

_f('This is %1$010.4f.', 3.14);
// This is 00003.1400.

_f('This is %1$ 12f.', 3.14);
// This is     3.140000.
// This is ␣␣␣␣3.140000.

_f('This is %1$ 10.4f.', 3.14);
// This is     3.1400.
// This is ␣␣␣␣3.1400.

_f('This is %1$+f.', 3.14);
// This is +3.140000.

_f('This is %1$+013f.', 3.14);
// This is +00003.140000.

_f('This is %1$+011.4f.', 3.14);
// This is +00003.1400.

_f('This is %1$+ 13f.', 3.14);
// This is     +3.140000.
// This is ␣␣␣␣+3.140000.

_f('This is %1$+ 11.4f.', 3.14);
// This is     +3.1400.
// This is ␣␣␣␣+3.1400.

_f('Hello %s!', 'Jane');
// Hello Jane!

_f('%1$s is %2$d years old.', 'John', 30);
// John is 30 years old.

Note: This uses the “printf” format string syntax, known from the C language (and also from PHP). In order to escape the percent sign (to use it literally), simply double it, as in 50 %%.

Note: When your format strings have more than one placeholder and replacement, always number the placeholders to avoid ambiguity and to allow for flexibility during translation. For example, instead of %s is from %s, use %1$s is from %2$s.

Strings with extended formatting

Wrap the sentences, phrases and labels of your user interface inside of the _fe function:

_fe('This is {0}.', 'Bob');
// This is Bob.

_fe('This is {0, number}.', 1003.14);
// This is 1,003.14.

_fe('This is {0, number, percent}.', 0.42);
// This is 42%.

_fe('This is {0, date}.', -14182916);
// This is Jul 20, 1969.

_fe('This is {0, date, short}.', -14182916);
// This is 7/20/69.

_fe('This is {0, date, medium}.', -14182916);
// This is Jul 20, 1969.

_fe('This is {0, date, long}.', -14182916);
// This is July 20, 1969.

_fe('This is {0, date, full}.', -14182916);
// This is Sunday, July 20, 1969.

_fe('This is {0, time}.', -14182916);
// This is 1:18:04 PM.

_fe('This is {0, time, short}.', -14182916);
// This is 1:18 PM.

_fe('This is {0, time, medium}.', -14182916);
// This is 1:18:04 PM.

_fe('This is {0, time, long}.', -14182916);
// This is 1:18:04 PM GMT-7.

_fe('This is {0, time, full}.', -14182916);
// This is 1:18:04 PM GMT-07:00.

_fe('This is {0, spellout}.', 314159);
// This is three hundred fourteen thousand one hundred fifty-nine.

_fe('This is {0, ordinal}.', 314159);
// This is 314,159th.

_fe('Hello {0}!', 'Jane');
// Hello Jane!

_fe('{0} is {1, number} years old.', 'John', 30);
// John is 30 years old.

Note: This uses the ICU “MessageFormat” syntax. In order to escape curly brackets (to use them literally), wrap them in single quotes, as in '{' or '}'. In order to escape single quotes (to use them literally), simply double them, as in it''s. If you use single quotes for your string literals in PHP, you also have to escape the inserted single quotes with backslashes, as in \'{\', \'}\' or it\'\'s.

Singular and plural forms

Wrap the sentences, phrases and labels of your user interface inside of the _p function:

_p('cat', 'cats', 1);
// cat

_p('cat', 'cats', 2);
// cats

_p('cat', 'cats', 3);
// cats

_p('The file has been saved.', 'The files have been saved.', 1);
// The file has been saved.

_p('The file has been saved.', 'The files have been saved.', 2);
// The files have been saved.

_p('The file has been saved.', 'The files have been saved.', 3);
// The files have been saved.

Singular and plural forms with formatting

Wrap the sentences, phrases and labels of your user interface inside of the _pf function:

_pf('There is %d monkey.', 'There are %d monkeys.', 0);
// There are 0 monkeys.

_pf('There is %d monkey.', 'There are %d monkeys.', 1);
// There is 1 monkey.

_pf('There is %d monkey.', 'There are %d monkeys.', 2);
// There are 2 monkeys.

_pf('There is %1$d monkey in %2$s.', 'There are %1$d monkeys in %2$s.', 3, 'Anytown');
// There are 3 monkeys in Anytown.

_pf('You have %d new message', 'You have %d new messages', 0);
// You have 0 new messages

_pf('You have %d new message', 'You have %d new messages', 1);
// You have 1 new message

_pf('You have %d new message', 'You have %d new messages', 32);
// You have 32 new messages

Note: This uses the “printf” format string syntax, known from the C language (and also from PHP). In order to escape the percent sign (to use it literally), simply double it, as in 50 %%.

Singular and plural forms with extended formatting

Wrap the sentences, phrases and labels of your user interface inside of the _pfe function:

_pfe('There is {0, number} monkey.', 'There are {0, number} monkeys.', 0);
// There are 0 monkeys.

_pfe('There is {0, number} monkey.', 'There are {0, number} monkeys.', 1);
// There is 1 monkey.

_pfe('There is {0, number} monkey.', 'There are {0, number} monkeys.', 2);
// There are 2 monkeys.

_pfe('There is {0, number} monkey in {1}.', 'There are {0, number} monkeys in {1}.', 3, 'Anytown');
// There are 3 monkeys in Anytown.

_pfe('You have {0, number} new message', 'You have {0, number} new messages', 0);
// You have 0 new messages

_pfe('You have {0, number} new message', 'You have {0, number} new messages', 1);
// You have 1 new message

_pfe('You have {0, number} new message', 'You have {0, number} new messages', 32);
// You have 32 new messages

Note: This uses the ICU “MessageFormat” syntax. In order to escape curly brackets (to use them literally), wrap them in single quotes, as in '{' or '}'. In order to escape single quotes (to use them literally), simply double them, as in it''s. If you use single quotes for your string literals in PHP, you also have to escape the inserted single quotes with backslashes, as in \'{\', \'}\' or it\'\'s.

Strings with context

Wrap the sentences, phrases and labels of your user interface inside of the _c function:

_c('Order', 'sorting');
// or
_c('Order', 'purchase');
// or
_c('Order', 'mathematics');
// or
_c('Order', 'classification');

_c('Address:', 'location');
// or
_c('Address:', 'www');
// or
_c('Address:', 'email');
// or
_c('Address:', 'letter');
// or
_c('Address:', 'speech');

Strings marked for later translation

Wrap the sentences, phrases and labels of your user interface inside of the _m function. This is a no-op instruction, i.e. (at first glance), it does nothing. But it marks the wrapped text for later translation. This is useful if the text should not be translated immediately but will later be translated from a variable, usually at the latest point in time possible:

_m('User');
// User

This return value could be inserted into your database, for example, and will always use the original string from the source code. Later, you could then use the following call to translate that string from a variable:

$text = 'User';
_($text);
// User

Extracting and updating translatable strings

In order to extract all translatable strings from your PHP files, you can use the built-in tool for this task:

# For the `mr-IN` locale, with the