windwalker/language

Windwalker Language package

3.4.4 2018-07-08 16:19 UTC

README

Windwalker Language is a simple i18n handler to process multi-language text.

Installation via Composer

Add this to the require block in your composer.json.

{
    "require": {
        "windwalker/language": "~3.0"
    }
}

Getting Started

Create an ini language file:

[en-GB]
WINDWALKER_LANGUAGE_TEST_FLOWER="Flower"
WINDWALKER_LANGUAGE_TEST_SAKURA="Sakura"
[zh-TW]
WINDWALKER_LANGUAGE_TEST_FLOWER=""

Now create Language instance and load language files.

use Windwalker\Language\Language;

$language = new Language;

// Load default language first
$language->load(__DIR__ . '/lang/en-GB.ini', 'ini');

// Load current language to override default.
$language->load(__DIR__ . '/lang/zh-TW.ini', 'ini');

Translate string:

// zh-TW has this language key, so it will be translated
$language->translate('WINDWALKER_LANGUAGE_TEST_FLOWER'); //

// This key not exists in zh-TW, use en-GB as default
$language->translate('WINDWALKER_LANGUAGE_TEST_SAKURA'); // Sakura

Key Format

All language key will be normalised to lowercase and separated by dot (.).

These cases all get same result:

$language->translate('WINDWALKER_LANGUAGE_TEST_FLOWER'); //
$language->translate('WINDWALKER_language_TEST FLOWER'); //
$language->translate('windwalker.language.test.flower'); //
$language->translate('Windwalker Language Test Flower'); //
$language->translate('Windwalker Language, Test Flower~~~!'); //

Replace String

WINDWALKER_LANGUAGE_TEST_BEAUTIFUL_FLOWER="The %s is beautiful~~~!!!"
$this->instance->sprintf('WINDWALKER_LANGUAGE_TEST_BEAUTIFUL_FLOWER', 'Sunflower');

// Result: The Sunflower is beautiful~~~!!!

Plural String

Create a Localise class:

// An example of EnGB Localise
namespace Windwalker\Language\Localise;

class EnGBLocalise implements LocaliseInterface
{
	public function getPluralSuffix($count = 1)
	{
		if ($count == 0)
		{
			return '0';
		}
		elseif ($count == 1)
		{
			return '';
		}

		return 'more';
	}
}

And prepare this language keys.

WINDWALKER_LANGUAGE_TEST_SUNFLOWER="Sunflower"
WINDWALKER_LANGUAGE_TEST_SUNFLOWER_0="No Sunflower"
WINDWALKER_LANGUAGE_TEST_SUNFLOWER_MORE="Sunflowers"

Now we can translate plural string.

$this->instance->plural('Windwalker Language Test Sunflower', 0); // No Sunflower
$this->instance->plural('Windwalker Language Test Sunflower', 1); // Sunflower
$this->instance->plural('Windwalker Language Test Sunflower', 2); // Sunflowers

Set locale and default language key in construct that language object can get default Localise to translate plural string if this string dose not exists in current locale:

$language = new Language('zh-TW', 'en-GB);

If Language Key Not Exists

Language object will return raw string which we send into it.

echo $language->translate('A Not Translated String');
echo "\n";
echo $language->translate('A_NOT_TRANSLATED_STRING');

Result:

A Not Translated String
A_NOT_TRANSLATED_STRING

Using Other Formats

Yaml

Yaml language file can write as nested structure.

windwalker:
    language.test:
        sakura: Sakura
        olive: Olive
$language->load(__DIR__ . '/lang/en-GB.yml', 'yaml');

$language->translate('windwalker.language.test.sakura'); // Sakura
$language->translate('WINDWALKER_LANGUAGE_TEST_OLIVE'); // Olive

Json

{
	"windwalker" : {
		"language-test" : {
			"sakura" : "Sakura",
			"olive" : "Olive"
		}
	}
}

The usage same as yaml.

$language->load(__DIR__ . '/lang/en-GB.json', 'json');

PHP

<?php

return array(
	'WINDWALKER_LANGUAGE_TEST_FLOWER' => "Flower",
	'WINDWALKER_LANGUAGE' => array(
			'TEST' => array(
				'SAKURA' => "Sakura"
			)
		)
);

The usage same as yaml.

$language->load(DIR . '/lang/en-GB.php', 'php');

Used Keys

// Get keys which have been used.
$language->getUsed();

Debug Mode

$language->setDebug(true);

We can get non-translated keys in debug mode.

echo $language->translate('A Translation Exists String');
echo "\n";
echo $language->translate('A Not Translated String');

$language->getOrphan(); // Array([0] => A Not Translated String);

And the output will be:

**A Translation Exists String**
??A Not Translated String??