Documentation

Locale
in package

Define a locale.

FULL AND PARTIAL LOCALES

Compare:

// FULL LOCALE - All localization services support this locale. $quebecois = new Locale([ 'nominal' => 'fr_CA', 'ts' => 'fr_CA', 'db' => 'fr_CA', 'moneyFormat' => 'fr_CA', 'uf' => 'fr_CA', ]); $quebecois->apply();

// PARTIAL LOCALE - Some localization services are not available, but the locale is still used. $chicano = new Locale([ 'nominal' => 'es_US', 'ts' => 'es_MX', 'db' => NULL, 'moneyFormat' => 'en_US', 'uf' => 'es_US', ]); $chicano->apply();

The existence of partial-locales is (perhaps) unfortunate but (at large scale) inevitable. The software comes with a list of 200 communication-locales (OptionValues), and admins may register more. There are only ~50 locales supported by ts() and 1-3 locales in the DB (for a typical business-entity). If you use any of these other locales, then some services must raise errors (or fallback to an alternate locale).

NEGOTIATION

The process of negotiation takes a requested locale and determines how to configure the localization services. For example, suppose a caller requests es_US (which isn't fully supported):

  • You could activate an adjacent locale which has full support (like es_MX or en_US).
  • You could activate es_US and mix elements from different locales (eg ts() uses es_MX; workflow-messages use es_US or es_MX, as available).

To negotiate an effective locale and apply it:

Locale::negotiate('es_US')->apply();

At time of writing, the negotiation behavior is based on system-setting partial_locales (which enables or disables support for partial locales). It may be useful to make this hookable.

It is also possible to perform a re-negotiation. For example, suppose the user requests locale es_US, and we're sending an automated email -- but we only have emails written for three languages.

$msgs = ['es_MX' => 'Buenos dias', 'en_US' => 'Good day', 'fr_CA' => 'Bon jour']; $locale = Locale::negotiate('es_US') ->renegotiate(array_keys($msgs)) ->apply(); $msg = $msgs[$locale->nominal];

In a world where you only allow fully supported locales, there would be no need for re-negotiation. However, if you have partially supported locales (with different mix of resources in each), then you need some defined behavior for unsupported edges (either raising an error or using a fallback).

Table of Contents

Properties

$nominal  : string
The official/visible name of the current locale.

Methods

__construct()  : mixed
apply()  : static
Activate this locale, updating any active PHP services that rely on it.
detect()  : Locale
Determine the current locale based on global properties.
negotiate()  : Locale
Negotiate an effective locale, based on the user's preference.
null()  : Locale
renegotiate()  : Locale
Re-negotiate the effective locale.
resolve()  : Locale
Lookup details about the desired locale.
getAllFallbacks()  : array<string|int, mixed>
getLocalePrecedence()  : array<string|int, string>
(Internal helper) Given a $preferred locale, determine a prioritized list of alternate locales.
pickFirstLocale()  : string|null
(Internal helper) Given a list of available locales and a general preference, pick the best match.

Properties

$nominal

The official/visible name of the current locale.

public string $nominal = ''

This can be any active locale that appears in communication preferences (eg civicrm_contact.preferred_language; ie option-group languages).

Tags
readonly

Methods

__construct()

public __construct([array<string|int, mixed> $params = [] ]) : mixed
Parameters
$params : array<string|int, mixed> = []

apply()

Activate this locale, updating any active PHP services that rely on it.

public apply() : static
Return values
static

detect()

Determine the current locale based on global properties.

public static detect() : Locale
Return values
Locale

negotiate()

Negotiate an effective locale, based on the user's preference.

public static negotiate(string $preferred) : Locale
Parameters
$preferred : string

The locale that is preferred by the user. Ex: en_US, es_ES, fr_CA

Tags
throws
CRM_Core_Exception
Return values
Locale —

The effective locale specification.

renegotiate()

Re-negotiate the effective locale.

public renegotiate(array<string|int, string> $availableLocales) : Locale

This is useful if you are beginning some business-transaction where the business record has localized resources. For example, a CiviContribute receipt might have different templates for a handful of locales -- in which case, you should choose among those locales.

The current implementation prefers to match the nominal language.

Parameters
$availableLocales : array<string|int, string>

List of locales that you know how to serve. Ex: ['en_US', 'fr_CA', 'es_MX']

Return values
Locale —

The chosen locale. If no good locales could be chosen, then NULL.

resolve()

Lookup details about the desired locale.

public static resolve(string|null $locale) : Locale
Parameters
$locale : string|null

The name of a locale that one wishes to use. The name may be NULL to use the current/active locale.

Return values
Locale

getAllFallbacks()

private static getAllFallbacks(string|null $preferred) : array<string|int, mixed>
Parameters
$preferred : string|null

ex: 'es_PR'

Return values
array<string|int, mixed> —

Ex: ['es_PR', 'es_419', 'es_MX', 'es_ES', 'en_US', 'en_GB]

getLocalePrecedence()

(Internal helper) Given a $preferred locale, determine a prioritized list of alternate locales.

private static getLocalePrecedence(string $preferred) : array<string|int, string>
Parameters
$preferred : string

Ex: 'es_PR'

Return values
array<string|int, string> —

Ex: ['es_PR', 'es_419', 'es_MX', 'es_ES']

pickFirstLocale()

(Internal helper) Given a list of available locales and a general preference, pick the best match.

private static pickFirstLocale(array<string|int, mixed> $availableLocales, array<string|int, mixed> $preferredLocales) : string|null
Parameters
$availableLocales : array<string|int, mixed>

Ex: ['en_US', 'es_MX', 'es_ES', 'fr_CA']

$preferredLocales : array<string|int, mixed>

Ex: ['es_PR', 'es_419', 'es_MX', 'es_ES']

Return values
string|null —

The available locale with the highest preference. Ex: 'es_MX'


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results