README

A modern internationalization system featuring JSON-format language files and efficient PHP-based caching. Supports dynamic language switching and real-time cache updates, ideal for rapid development and deployment of multilingual websites and applications.

Features

Supports multiple language files
Automatic caching of translation data for improved performance
Supports organization of translation keys by namespaces
Configurable translation file directory and cache directory

Requirements

Composer

File Structure

Here's an example of the expected file structure:

.
├── cache
├── lang
│   ├── en_US
│   │   ├── general.json
│   │   └── greeting.json
│   └── zh_TW
│       ├── general.json
│       └── greeting.json
├── src
│   ├── /...
│   └── I18n.php
└── vendor

Installation

Use Composer to install the I18n class library into your project:

composer require carry0987/i18n

Usage

After installation, you can include the I18n class in your project with Composer's autoloading:

require_once 'vendor/autoload.php';

use carry0987\I18n\I18n;

$i18n = new I18n([
    'useAutoDetect' => true, // By default, the language is automatically detected
    'langFilePath' => 'path/to/lang', 
    'cachePath' => 'path/to/cache'
]);

Fetch translations:

// Use file name and key to get the translation value
echo $i18n->fetch('greeting.hello'); // Outputs: "Hello"

Fetch multiple translations:

// Get multiple translations in the current language
$translations = $i18n->fetchList(); // Empty parameter returns all translations

Note

When accessing translations, the keys used must follow the format: filename.key, which ensures that each translation value is extracted from the specified file.

Advanced Usage

If set useAutoDetect to true, the language will be automatically detected from the browser's Accept-Language header. If the language is not supported, the default language will be used. Also, if you want to change cookie settings, you can set the cookie option:

$config = array(
    'useAutoDetect' => true,
    //...
    'cookie' => array(
        'name' => 'lang',
        'expire' => time()+864000,
        'path' => '/',
        'domain' => '',
        'secure' => true,
        'httponly' => true
    )
);

You can set the language code manually:

$i18n = new I18n([
    'useAutoDetect' => false, // Set useAutoDetect to false to disable automatic language detection
    //...
]);
// Initialize the language settings
$i18n->initialize('en_US'); // 'en_US' is the language code

Load specific language files:

$i18n = new I18n([
    'allowedFiles' => ['general', 'greeting'], // Set the list of language files to be loaded
    //...
]);

Set language aliases:

// Define aliases for languages
$i18n->setLangAlias(array('en_US' => 'English', 'zh_TW' => '繁體中文'));

// Fetch the list of languages with their aliases
$aliasedLangList = $i18n->fetchLangList();
// Outputs: array('en_US' => 'English', 'zh_TW' => '繁體中文')

carry0987 / i18n

Maintainers

Details