Lang

Language files can be loaded and variables displayed via this library. This library extends the config library and also handles locale setting (and getting).

It is worth noting that Outlast Framework handles configuration and language variables as the same. This is because they use the same syntax within the template system: {{#variable_name#}}. So actually if you set a config variable, it will also be available as a language variable and vice versa. In other words, choose your variable names accordingly to avoid mixups.

Read the related section in the template syntax documentation for more details.

Properties

variable The one public property of this library is the variable object. This is a stdClass object that contains all of the language variable values by key. It is a read-only value, but you can set its value using set_variables(). This is the same key/value pair object as the one pointed to by the config library.

Example:

$this->zajlib->lang->variable->my_language_variable

load()

Loads up the language file. The file name should be specified relative to the conf folder. Files can be located in any of the lang folders of active plugins and will be loaded according to plugin hierarchy.

$this->zajlib->lang->load($config_file_name)

@param string $lang_file_name The file name should be specified relative to the lang folder. The file name can be given as a full name (‘sample.en_US.lang.ini’) or as a name (‘sample’) – in the later case it will find the one for the current locale, so name.CURRENT_LOCALE.lang.ini.
@param string $section The section to compile. If false (or left empty) the entire file will be compiled.
@param boolean $force_set This will force setting of variables even if the same file / section was previously loaded. Defaults to false.
@param boolean $fail_on_error If set to true (the default), it will fail with fatal error.
@return boolean Returns true if successful, false otherwise.

get()

Get the current locale (en_US for example).

$this->zajlib->lang->get()

@return string Returns the four-letter locale code that is currently set.

set()

Set the current locale (en_US for example).

$this->zajlib->lang->set('en_US')

@param bool|string $new_language If set, it will try to choose this locale. Otherwise the default locale will be chosen.
@return string Return the locale code that was set.

get_code()

Get the current two-letter language code (en for example).

$this->zajlib->lang->get_code()

@return string Returns the two-letter language code that is currently set.

set_by_code()

Set the current locale (en_US for example).

$this->zajlib->lang->set_by_code('en');

@param bool|string $new_language If set, it will try to choose this language. Otherwise the default langauge will be chosen based on the default locale.
@return string The two-letter language code based on current locale.

auto()

Try to set the locale automatically first by querystring, then by cookie, then by subdomain, then by top level domain, finally by default. Saves a cookie for next page load.

$this->zajlib->lang->auto();

@return string The locale code that was just set.

set_variation()

Set language variation, typically useful for applying formal variations of a locale.

Sets language variation to formal at runtime:

$this->zajlib->lang->set_variation('formal')

Turns variation off at runtime:

$this->zajlib->lang->set_variation(false)

You can also set $zajconf['locale_variation'] in site/index.php which will set the language variation for the entire web app.

You’ll also need to define variation language files – see documentation.

get_default_locale()

Get default locale.

$this->zajlib->lang->get_default_locale()

@return string Returns the hard-coded default locale.

is_default_locale()

Returns true if the current locale is the default locale.

$this->zajlib->lang->is_default_locale()

@return boolean True if the current locale, false otherwise.

get_locales()

Get all locales.

$this->zajlib->lang->get_locales()

@return array Returns an array of all available locales.

get_codes()

Get all the available two-letter language codes.

$this->zajlib->lang->get_codes()

@return array Returns an array of all available language codes.

reload_locale_settings()

Reload all the available locales and default locale settings. Typically only used in unit tests or system stuff.

$this->zajlib->lang->reload_locale_settings()

template()

Display a specific template by searching for a locale file first.

(If the request contains zaj_pushstate_block, it will reroute to block. See Mozajik pushState support for more info.)

$this->zajlib->lang->template($source_path, $force_recompile = false, $return_contents = false, $custom_compile_destination = false)

@param string $source_path The path to the template to be compiled relative to the active view folders.
@param boolean $force_recompile If set to true, the template file will be recompiled even if a cached version already exists. (False by default.)
@param boolean $return_contents If set to true, the compiled contents will be returned by the function and not sent to the browser (as is the default).
@param boolean|string $custom_compile_destination If set, this allows you to compile the template to a different location than the default. This is not recommended unless you really know what you are doing!
@return string If requested by the $return_contents parameter, it returns the entire generated contents.

block()

Extracts a specific block from a template and displays only that. This is useful for ajax requests.

$this->zajlib->lang->block($source_path, $block_name, $force_recompile = false, $return_contents = false)

@param string $source_path The path to the template to be compiled relative to the active view folders.
@param string $block_name The name of the block within the template.
@param boolean $force_recompile If set to true, the template file will be recompiled even if a cached version already exists. (False by default.)
@param boolean $return_contents If set to true, the compiled contents will be returned by the function and not sent to the browser (as is the default).
@return string If requested by the $return_contents parameter, it returns the entire generated contents.

convert_eng()

Converts a string to their standard latin-1 alphabet counterparts.

$this->zajlib->lang->convert_eng($str, $strip_newlines = true)

@param string $str The original accented UTF string.
@param boolean $strip_newlines If set to true, new lines will be removed.
@return string Returns a string without accents.

strip_chars()

Strip non-alpha-numerical characters from a string.

$this->zajlib->lang->strip_chars($str, $convert_accents = true)

@param string $str The original accented string.
@param boolean $convert_accents If set to true, accented characters will be converted before everything is stripped.
@return string Returns a string without accents and only alpha-numerical characters

strip_chars()

Converts a string from one encoding to another.

$this->zajlib->lang->convert($str, $to="ISO-8859-1", $from="UTF-8", $use_iconv = false)

@param string $str The original string.
@param string $to The destination encoding. ISO latin 1 by default.
@param string $from The original encoding. UTF-8 by default.
@param boolean $use_iconv Will force the function to use iconv. This will work on some systems, not on others.
@return string Returns a string converted to the new encoding.

set_variables()

Sets the key/value variable object. Be careful, this overwrites the entire current setting. Because conf and lang are actually the same both conf and lang variables will be overwritten.

Typically you should not use this method in the course of normal program logic – it’s useful for testing and other purposes.

$variables = (object) array('a_key'=>'A value', 'b_key'=>'B value');
$this->zajlib->config->set_variables($variables);

@param stdClass $variables The key/value pairs to use for the new variable.
@return boolean Always returns true.

reset_variables()

Sets the key/value variable object. Be careful, this overwrites the entire current setting. Because conf and lang are actually the same both conf and lang variables will be overwritten.

Typically you should not use this method in the course of normal program logic – it’s useful for testing and other purposes.

$this->zajlib->config->reset_variables();

@return boolean Always returns true.

Other methods

Additional methods are available in this library but are reserved for system use. See full, generated documentation for more info.