eufony / i18n
A simple but naive approach to token-based internationalization.
Requires
- php: ^8.1
- eufony/dbal: v0.1.0-beta1
Requires (Dev)
- phpunit/phpunit: ^9.5
Suggests
- eufony/i18n-store-implementation: Virtual package for token store implementations.
Provides
- eufony/i18n-store-implemtation: v1.x-dev
This package is auto-updated.
Last update: 2024-10-17 09:24:12 UTC
README
eufony/i18n provides an easy-to-use but limited token-based approach to internationalization.
eufony/i18n is a PHP library that allows defining and retrieving translated messages, called tokens. It provides a
common interface for fetching tokens from different backends; with the explicit goal of providing a naive approach to
varying grammatical rules, which is simpler than a more complete system such as
GNU gettext
.
Interested? Here's how to get started.
Getting started
Installation
eufony/i18n is released as a Packagist package and can be easily installed via Composer with:
composer require "eufony/i18n:v1.x-dev"
Warning: This package does not have any stable releases yet (not even a v0.x pre-release) and is currently unstable. Expect frequent breaking changes and instability!
Basic Usage
eufony/i18n provides two main classes to provide translation facilities: Stores
and a Translator
. Stores provide
the actual Tokens
that contain the translated messages. The Translator
class acts as a front-end to using a store.
To get started, choose a store implementation and pass it to a new translator, like so:
$store = /* ... */; $translator = new Translator($store);
Out of the box, eufony/i18n provides two different store implementations:
// Fetch tokens from PHP arrays // You could also for example parse this array from a JSON string $store = new ArrayStore(["greetings.weather.good" => ["en" => "...", "de" => "...", "ru" => "..."]]); $store = ArrayStore::fromJSON(File::read("extras/i18n/tokens.json")); // `File` requires `eufony/filesystem` // Fetch tokens from an SQL database using the `eufony/dbal` abstraction layer $connection = new Connection(/* ... */); // a `Connection` instance from `eufony/dbal` $store = new SQLStore($connection);
Once the translator is initialized, you can start using it to translate messages or fetch tokens. Tokens are pre-translated messages that have been fed into the store, whereas translations may happen on-the-fly depending on the store implementation.
$greeting = $translator->translate("Hello, {user}.", ["en" => "de"]); // if we only need a single target language $greeting = $translator->translate("Hello, {user}.", ["en" => ["de", "ru"]]); // for multiple target languages $weather = $translator->token("greetings.weather.good"); // Once we have our tokens, we can use `get()` to extract the messages in the target languages echo $greeting->interpolate(["user" => "Euphie"])->get("de"); echo $weather->get("de");
The constructor of the Translator
class can also take an option preferredLanguage
parameter, which will specify a
default translation language. You can use this to simplify some of these calls if you already know the target language
beforehand.
$translator = new Translator($store, preferredLanguage: "de"); // Now, we can assume the target language to be the preferred language by default // But we can still override it for specific situations like above $greeting = $translator->translate("Hello, {user}.", "en"); $weather = $translator->token("greetings.weather.good"); // If the preferred language is set, tokens can be converted to strings automatically // No more need to call `get()` every time echo $greeting->interpolate(["user" => "Euphie"]); echo $weather;
Contributing
Found a bug or a missing feature? You can report it over at the issue tracker.
License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses/.