FastSitePHP\Lang\I18N

Internationalization (I18N) API

This class provides an easy to use API for sites and apps that need to support multiple languages.

[i18n] is spelled "Internationalisation" in British English. [i18n] is an acronym/numeronym that represents ("i" + 18 characters + "n"). The difference is US English uses "z" while British English uses an "s" in the spelling of the word.

Using this class requires a global [\FastSitePHP\Application] object to be assigned to the variable [$app].

Código Fonte

Links Relacionados

• https://en.wikipedia.org/wiki/Internationalization_and_localization
• https://www.w3.org/International/questions/qa-i18n

Código de Exemplo

// O FastSitePHP provê uma API de Internacionalização (i18n) de fácil
// utilização para sites e apps que precisam suportar múltiplos idiomas.
// O código é estruturado mas mínimo em seu tamanho, assim se você tem
// necessidades diferentes de tradução, você pode simplesmente copiar e
// modificar a classe.

// Traduções são salvas como arquivos JSON no mesmo diretório utilizando o
// formato de nome “{nome}.{idioma}.json”. Um arquivo principal opcional
// nomeado “_.{idioma}.json” se encontrado será lido primeiro. O arquivo
// principal "_" é útil para armazenar traduções chave tal como menus,
// cabeçalho de página, rodapés de páginas etc.

// Um idioma de fallback opcional pode ser especificado assim traduções
// não encontradas são obtidas de outro idioma. Isto permite que sites
// parcialmente traduzidos utilizem esta API.

// Já que a API é simples e fácil de utilizar, existem somente duas funções
// para chamar:
// [langFile()] e [textFile()].

// Arquivos de Exemplo:
//     _.en.json
//     _.es.json
//     header.en.json
//     header.es.json
//     about.en.json

// Utilizando este código, os aquivos acima serão carregados na ordem listada.
$app->config['I18N_DIR'] = __DIR__ . '/i18n';
$app->config['I18N_FALLBACK_LANG'] = 'en';

\FastSitePHP\Lang\I18N::langFile('header', 'es');
\FastSitePHP\Lang\I18N::langFile('about', 'es');

// Uso típico é permitido para um app carregar um arquivo de idioma
// baseando-se na URL Requisitada:
$app->get('/:lang/about', function($lang) {
    \FastSitePHP\Lang\I18N::langFile('about', $lang);
});

// [setup()] pode ser chamada por cada requisição para ter certeza que o
// arquivo de idioma seja sempre carregado para a renderização de um modelo
// quando [$app->render()] é chamada.
//
// Isto é útil se seu site utiliza PHP ou outros modelos para renderizar e
// espera que o arquivo [i18n] padrão sempre esteja disponível. Por exemplo
// um erro inesperado ou chamada de [$app->pageNotFound()] pode acionar um
// modelo para que seja renderizado.
\FastSitePHP\Lang\I18N::setup($app);

// Traduções carregadas são definidas na propriedade da app
// ($app->locals['i18n']), de forma que elas podem ser utilizadas com
// renderização de modelo e chamada de página.

// Ao utilizar um formato de URL [https://www.example.com/{lang}/{pages}]
// e um idioma fallback, o usuário será redirecionado para a mesma página
// com o idioma fallback se o idioma especificado não existir.

// Quando [langFile()] é chamada e o idioma é verificado como válido, isto é
// definido na propriedade do app ($app->lang).

// A outra função I18N [textFile()] simplesmente recebe um caminho completo
// de arquivo contento o texto '{lang}' juntamente com o idioma selecionado
// e então carrega o arquivo ou, se este não existir, o arquivo que
// corresponde ao idioma de fallback.
$file_path = $app->config['I18N_DIR'] . '/test-{lang}.txt';
$content = \FastSitePHP\Lang\I18N::textFile($file_path, $app->lang);

Propriedades

Métodos

langFile($file_name, $lang)

This function read JSON files from a directory specified in the config setting ($app->config['I18N_DIR']) and then loaded translations are set to the app property ($app->locals['i18n']) so that they can be used with template rendering and from the calling page. When the language is verified as valid it is set to the app property ($app->lang).

All JSON files need to be in the same directory and have a format of [{name}.{lang}.json]. An optional main file named [_.{lang}.json] if found will first be loaded when this function is called.

A fallback language can be specified so that missing translations default to another language. This allows partially translated sites to use this API. Fallback language is set as config setting ($app->config['I18N_FALLBACK_LANG']).

If a fallback language is defined and the language specified is not matched and the requested url has a format of [https://www.example.com/{lang}/{pages}] then this function will redirect to the fallback language and end PHP processing.

The file specified as a parameter to this function (or optional fallback) is required to exist; if not an exception is thrown. This paramater is not intended to be a based on user input however the generated file name is validated for security in case an app sets the value based on user input.

Example Files:
    _.en.json
    _.es.json
    header.en.json
    header.es.json
    about.en.json

Example Code:
    // Assuming the files above exist they would be loaded
    // in the order shown above based on this code.
    $app->config['I18N_DIR'] = __DIR__ . '/i18n';
    $app->config['I18N_FALLBACK_LANG'] = 'en';
    I18N::langFile('header', 'es');
    I18N::langFile('about', 'es');

    // Typical usage is allow for an app to load a language
    // file based on the Requested URL:
    $app->get('/:lang/about', function($lang) {
        I18N::langFile('about', $lang);

textFile($file_path, $lang)

Return the contents of a file based on the User's selected language.

Just like the function [langFile()] ths function uses a fallback language from the Application config settings to handle partially translated sites.

[$file_path] is a full file path requires the text '{lang}' anywhere in the file path. The '{lang}' value gets replaced wiht the user's selected language. This paramater is intended to be hard-coded by the app and users should not have the ability to input their own file paths as it would be a security risk.

The file is required to exist (either selected language or fallback language) otherwise an exception is thrown.

Example Code:
    // Config Option
    $app->config['I18N_FALLBACK_LANG'] = 'en';

    // Typical usage is allow for an app to load file content
    // based on the the User's Selected Language:
    $app->get('/:lang/sample-code', function($lang) {
        $file_path = __DIR__ . '/../app_data/files/sample-code-{lang}.txt'
        return I18N::textFile($file_path, $lang);

Retorna: string

getUserDefaultLang()

Return the default language for the user based on the 'Accept-Language' request header and available languages for the site.

This is useful to provide custom content for the user or to redirect to the user's language when they access the default URL.

Requires config values:
    $app->config['I18N_DIR']
    $app->config['I18N_FALLBACK_LANG']

Example usage:
    $app->redirect($app->rootUrl() . I18N::getUserDefaultLang() . '/');

Retorna: string

hasLang($lang)

Return true if the language is supported by the site. For a language to be supported it must include a '_.{lang}.json' file in the [I18N_DIR] directory.

Requires config value:
    $app->config['I18N_DIR']

Retorna: bool

setup(Application $app)

Static function that can be called for each request to make sure that a language file is always loaded for template rendering when [$app->render()] is called.

This is useful if your site uses PHP or other templates for rendering and expects the [i18n] default file to always be available. For example an unexpected error or call to [$app->pageNotFound()] can trigger a template to be rendered.