bayfrontmedia/translation

A PHP translation library utilizing multiple language storage options.

v2.0.0 2023-01-26 16:53 UTC

Requires

• php: ^8.0
• ext-json: *
• ext-pdo: *
• bayfrontmedia/php-array-helpers: ^2.0

MIT

• John Robinson

• php
• translation
• translate

README

A PHP translation library utilizing multiple language storage options.

• License
• Author
• Requirements
• Installation
• Usage

License

This project is open source and available under the MIT License.

Author

• Bayfront Media homepage
• Bayfront Media GitHub

Requirements

• PHP ^8.0
• JSON PHP extension
• PDO PHP extension

Installation

composer require bayfrontmedia/translation

Usage

NOTE: It is up to you to populate the translation data, no matter where it is stored. This library simply reads the existing data from its source.

Storage adapter

A Bayfront\Translation\ApadpterInterface must be passed to the Bayfront\Translation\Translate constructor. There are a variety of storage adapters available, each with their own required configuration.

Defined array

The defined array adapter allows you to use a predefined array containing all of your translations.

use Bayfront\Translation\Adapters\DefinedArray;

$adapter = new DefinedArray([
    'en' => [ // Locale
        'dashboard' => [ // ID
            'title' => 'Account dashboard',
            'greeting' => 'Welcome back, {{name}}'
        ]
    ]
]);

Local

The local adapter allows you to use local native PHP files containing all of your translation arrays.

use Bayfront\Translation\Adapters\Local;

$adapter = new Local('/root_path');

The file structure from the root path should be:

/root_path
    /locale
        /id.php

For example, if the locale is set as en, the method say('dashboard.greeting') will search for the file /root_path/en/dashboard.php, and the array key greeting.

Example dashboard.php:

<?php

return [
    'title' => 'Account dashboard',
    'greeting' => 'Welcome back, {{name}}'
];

PDO

The PDO adapter allows you to use a \PDO instance for language retrieval from a database, and may throw a Bayfront\Translation\AdapterException exception in its constructor.

To create a compatible table, execute the following statement:

CREATE TABLE IF NOT EXISTS table_name (
    `locale` varchar(80) NOT NULL, 
    `id` varchar(255) NOT NULL, 
    `contents` longtext NOT NULL, 
    UNIQUE KEY unique_index(locale,id))

This table structure ensures only one row exists with a matching locale and id. The contents column should contain a JSON encoded array.

The PDO adapter will create/use a table named "translations" unless otherwise specified in the constructor.

use Bayfront\Translation\Adapters\PDO;

try {

    $adapter = new PDO($dbh, 'table_name');

} catch (AdapterException $e) {
    die($e->getMessage());
}

Start using Translation

Once your adapter has been created, it can be used with Translation. In addition, a string defining the locale should be passed to the constructor.

The last argument is true by default. When true, if a translation is not found and $default = NULL, the original string is returned. If false, a Bayfront\Translation\TranslationException is thrown.

use Bayfront\Translation\Translate;

$translate = new Translate($adapter, 'en', true);

Public methods

• getLocale
• setLocale
• getTranslations
• addTranslations
• get
• say
• replace
• replaceAll

getLocale

Description:

Get locale.

Parameters:

• None

Returns:

• (string)

Example:

echo $translate->getLocale();

setLocale

Description:

Set locale.

Parameters:

• $locale (string)

Returns:

• (self)

Example:

$translate->setLocale('es');

getTranslations

Description:

Return array of all known translations.

Translations are only "known" once their ID has been used, or they have been added via the addTranslations method.

Parameters:

• None

Returns:

• (array)

Example:

$translations = $translate->getTranslations();

addTranslations

Description:

Add translations to the known translations for the current request only.

Parameters:

• $translations (array)

Returns:

• (self)

Example:

$translate->addTranslations([
    'en' => [ // Locale
        'dashboard' => [ // ID
            'title' => 'New account dashboard'
        ]
    ],
    'es' => [
        'dashboard' => [
            'greeting' => 'Bienvenidos, {{name}}'
        ]
    ]
]);

get

Description:

Return the translation for a given string.

The string format is: id.key. Keys are in array dot notation, so they can be as deeply nested as needed.

Replacement variables should be surrounded by {{ }} in the original string.

If a translation is not found and $default = NULL, either the original string is returned, or a TranslationException is thrown, depending on the setting chosen in the constructor.

Parameters:

• $string (string)
• $replacements = [] (array)
• $default = NULL (mixed): Default value to return if translation is not found

Returns:

• (mixed)

Throws:

• Bayfront\Translation\TranslationException

Example:

$title = $translate->get('dashboard.title');

// Example with replacements

$greeting = $translate->get('dashboard.greeting', [
    'name' => 'John'
]);

say

Description:

Echos the translation for a given string.

Parameters:

• $string (string)
• $replacements = [] (array)
• $default = NULL (mixed): Default value to return if translation is not found

Returns:

• (void)

Throws:

• Bayfront\Translation\TranslationException

Example:

$translate->say('dashboard.title');

replace

Description:

Replace case-sensitive values in a string.

Parameters:

• $string (string): Original string
• $replacements = [] (array): Array of values and replacements

Returns:

• (string)

Example:

$title = $translate->get('dashboard.title');

echo $translate->replace($title, [
    'dashboard' => 'homepage'
]);

replaceAll

Description:

Replace multiple case-sensitive values in a string with a single replacement.

Parameters:

• $string (string): Original string
• $values (array): Array of values to replace
• $replacement (string)

Returns:

• (string)

Example:

echo $translate->replaceAll($user_comment, [
    'array',
    'of',
    'bad',
    'words'
], '**CENSORED**');