Transcribe
![Software License][ico-license]
![Coverage Status][ico-coverage]
, (*1)
Transcribe is a simple localization package written in PHP in which the translated word can be retrieved easily based on the specified locale. A localization source can be from multiple .php files or from a database connection using PDO., (*2)
Installation
Install the Transcribe package via Composer:, (*3)
``` bash
$ composer require rougin/transcribe, (*4)
## Basic usage
Prior in using `Transcribe`, a list of words must be provided with its specified translations (e.g., `fil_PH.php`):
``` php
// locales/fil_PH.php
$texts = array();
$texts['language'] = 'linguahe';
$texts['name'] = 'pangalan';
$texts['school'] = 'paaralan';
return $texts;
Once provided, specify the words in a source (e.g., FileSource):, (*5)
``` php
// index.php, (*6)
use Rougin\Transcribe\Source\FileSource;, (*7)
// ..., (*8)
$source = new FileSource;, (*9)
// Add the directory to the source ----
$source->addPath(DIR . '/locales');
// ------------------------------------, (*10)
After creating the specified source, use the `get` method from the `Locale` class to get the localized word based on its keyword:
``` php
// index.php
use Rougin\Transcribe\Locale;
// ...
/** @var \Rougin\Transcribe\Source\FileSource */
$source = /** ... */;
$locale = new Locale($source);
echo $locale->get('fil_PH.name');
``` bash
$ php index.php
pangalan, (*11)
Using the `setDefault` method can define the default locale. With this, there is no need to specify it when using the `get` method:
``` php
// index.php
$locale->setDefault('fil_PH');
// No need to specify "fil_PH" ---
echo $locale->get('name');
// -------------------------------
Using sources
The previous example uses the FileSource which uses .php files in getting localized words. But Transcribe also provides a way in getting the said localized words through a database using the PdoSource:, (*12)
``` php
// index.php, (*13)
use Rougin\Transcribe\Source\PdoSource;, (*14)
// ..., (*15)
// Create a PDO instance -----------------
$dsn = 'mysql:host=localhost;dbname=demo';, (*16)
$pdo = new PDO($dsn, 'root', /** ... */);
// ---------------------------------------, (*17)
$source = new PdoSource($pdo);, (*18)
// ..., (*19)
When using the `PdoSource` class, it can also specify the database table and its columns to be used for getting the localized words:
Contents of the "locales" table
id |
type |
name |
text |
| 1 |
fil_PH |
name |
pangalan |
| 2 |
fil_PH |
school |
paaralan |
``` php
// ...
// Use "locales" table from database ---
$source->setTableName('locales');
// -------------------------------------
// Use "type" column from "locales" table ---
$source->setTypeColumn('type');
// ------------------------------------------
// Use "name" column from "locales" table ---
$source->setNameColumn('name');
// ------------------------------------------
// Use "text" column from "locales" table ---
$source->setTextColumn('text');
// ------------------------------------------
// ...
[!NOTE]
If the required table and columns were not specified, its default values are the same from the above-example (e.g., locales for table, and type, name, and text values for the columns)., (*20)
Then use the same get method from Locale class to get the localized word from the database table:, (*21)
``` php
// index.php, (*22)
// ..., (*23)
echo $locale->get('fil_PH.name');, (*24)
``` bash
$ php index.php
pangalan
Creating custom sources
To create a custom source, kindly use the SourceInterface for its implementation:, (*25)
``` php
namespace Rougin\Transcribe\Source;, (*26)
interface SourceInterface
{
/**
* Returns an array of words.
*
* @return array<string, array<string, string>>
*/
public function words();
}, (*27)
The `words` method should return a list of words in an associative array format:
``` php
return array(
'fil_PH' => array(
'language' => 'linguahe',
'name' => 'pangalan',
'school' => 'paaralan',
),
);
The specified method will be used as the reference for finding the localized word from the get method of Locale class., (*28)
Migrating to the v0.4.0 release
The new release for v0.4.0 will be having a backward compatibility break (BC break). With this, some functionalities from the earlier versions might not be working after upgrading. This was done to increase extensibility, simplicity and maintainbility. This was discussed in one of my blog post which also mentions Transcribe:, (*29)
I also want to extend this plan to my personal packages as well like Staticka and Transcribe. With this, I will introduce backward compatibility breaks to them initially as it is hard to migrate their codebase due to minimal to no documentation being provided in its basic usage and its internals. As I checked their code, I realized that they are also over engineered, which is a mistake that I needed to atone for when updating my packages in the future., (*30)
Please see Pull Request #1 for the files that were removed or updated in this release and the UPGRADING page for the specified breaking changes., (*31)
Changelog
Please see CHANGELOG for more information what has changed recently., (*32)
Testing
bash
$ composer test, (*33)
Credits
License
The MIT License (MIT). Please see LICENSE for more information., (*34)
Wallogit.com
