Solar is designed with built-in localization support. This means you can create a locale file for any Solar class and provide your own localized strings for output.
When you call Solar::start(), Solar automatically registers a Solar_Locale object under the name 'locale'. To work with locales, you need to retrieve this object from the registry, like so:
<?php
require_once 'Solar.php';
Solar::start('/path/to/config/Solar.config.php');
$locale = Solar_Registry::get('locale');
?>Note: Normally you will never need to use the registered Solar_Locale object directly. Instead, in classes descended from Solar_Base, you will use $this->locale().
As you scan through the Solar distribution, you will see that many class
directories have a Locale/ subdirectory. That subdirectory will have at
least one file in it, en_US.php. That contains the localization strings for
the en_US locale. As Solar gains acceptance, we expect to build more locale
files for each localization (e.g., 'de_DE' for German, 'pt_BR' for Brazilian
Portuguese, and so on).
As with the config file, locale files are simply PHP scripts that return an array. Thus, the simplest possible locale file is an empty array:
<?php
return array();
?>Each array is composed of a translation key and at least one string value (the translated version of the key). For example:
<?php
return array(
'TEXT_HELLO' => 'Hello.',
'TEXT_APPLE' => 'apple',
);
?>(When creating a locale file, be sure to follow the naming conventions regarding translation string keys.)
If this locale file were associated with a class called Solar_Example,
you would retrieve the translated strings like so:
<?php
// get the locale object
$locale = Solar_Registry::get('locale');
// load the Solar_Example locale file for the current country-code,
// and retrieve the translation for the 'TEXT_HELLO' key.
$text = $locale->fetch('Solar_Example', 'TEXT_HELLO');
?>Alternatively, if you were working with a class extended from
Solar_Base, you would call $this->locale() with the just the
translation key (cf. the Solar_Base::locale() method).
Sometimes you need to specify different singular and plural versions of a translation. In this case, the translation value is an array where the first element is the singular version, and the second element is the plural version.
<?php
return array(
'TEXT_HELLO' => 'Hello.',
'TEXT_APPLE' => array('apple', 'apples'),
);
?>You then call the fetch() method with a numeric value, and it picks the proper translation based on the number. For example:
<?php
// get the locale object
$locale = Solar_Registry::get('locale');
// zero 'apples'
$text = $locale->fetch('Solar_Test_Example', 'TEXT_APPLE', 0);
// one 'apple'
$text = $locale->fetch('Solar_Test_Example', 'TEXT_APPLE', 1);
// five 'apples'
$text = $locale->fetch('Solar_Test_Example', 'TEXT_APPLE', 5);
?>If you use Solar_Locale to request a translation key that does not exist for a specific class, it falls back along the class hierarchy to the translation keys found in parent classes. This means that child classes can override as many or as few translation strings as they wish, because they always have recourse to the parent-class strings.
As a final fallback, Solar_Locale will look in Solar/Locale/* for
vendor-wide translations; if it cannot find them there, it returns the key
itself as the translation.
This means translation strings never come back as blank; at the worst, you will see the translation key where the localized text should be.
You can change from one locale code to another using Solar_Locale::setCode(). When you do, it will automatically reload strings for the new locale as you make calls to Solar_Locale::fetch().
You can find the current locale code using Solar_Locale::getCode(), or just the current country code using Solar_Locale::getCountryCode().