Download the PHP package pinga/locale without Composer

Pinga Locale

Internationalization and localization for PHP

Provide your application in multiple languages, to users in various countries, with different formats and conventions. Based on the wonderful delight-im/PHP-I18N.

Requirements

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

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

macOS: To generate the po and mo files with the packaged bash script, install gnu-sed.

Installation

1. Include the library via Composer [?]:

2. Copy the i18n bash script to the root of your project

3. Include the Composer autoloader:

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:

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

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.

Directory and file names for translation files

Your translation files will later have to be stored in the following location relative to the root of your project:

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

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:

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:

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:

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:

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:

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:

Strings with formatting

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

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:

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:

Singular and plural forms with formatting

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

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:

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:

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:

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:

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:

This creates or updates a PO (Portable Object) file for the specified language, which you can then translate, share with your translation team, or send to external translators.

If you only need a generic POT (Portable Object Template) file with all extracted strings, which is not specific to a certain language, just leave out the argument with the locale code (or set it to an empty string):

Translating the extracted strings

Whoever handles the actual task of translating the extracted strings, whether it’s you, your translation team, or external translators, the people in charge will need the PO (Portable Object) file for their language, or, in some cases, the generic POT (Portable Object Template) file.

Just open the file in question and search for strings with msgstr "" below them. These are the strings with empty translations that you still need to work on. In addition to that, any string with #, fuzzy above it has had a translation before but the original string in the source code changed, so the translation must be reviewed (and the “fuzzy” flag or comment removed).

Exporting translations to binary format

After you have worked on your translations and saved the PO (Portable Object) file for a language, you need to run the command from “Extracting and updating translatable strings” again in order to export these translations to a binary format.

They will then be stored in a MO (Machine Object) file alongside your PO (Portable Object) file, ready to be automatically picked up and inserted in place of the original strings.

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

When using I18n#setLocaleAutomatically to determine and activate the correct locale for the user automatically, you can control which locales to consider similar or related. Thus you can control the way lookups and comparisons of locales work.

If the default behavior doesn’t work for you, simply provide the optional first argument, called $leniency, to I18n#setLocaleAutomatically. The following table lists the minimum leniency value that is required to match the two locale codes in question:

Troubleshooting

• Translations are usually cached, so it may be necessary to restart the web server for any changes to take effect.

Contributing

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.

License

This project is licensed under the terms of the MIT License.