README

A PHP class for converting strings between character encodings, without relying on the iconv extension.

Installation

composer require atk14/translate

Usage

Converting between encodings

$iso = Translate::Trans($utf8_string, "UTF-8", "ISO-8859-2");
$utf8 = Translate::Trans($iso_string, "ISO-8859-2", "UTF-8");
$win  = Translate::Trans($utf8_string, "UTF-8", "Windows-1250");

If a conversion is not supported, the original string is returned unchanged.

Converting arrays

When $text is an array, all string values are converted recursively. Non-string values (integers, nulls, ...) are left as-is.

$data = ["name" => "Žofie", "age" => 42];
$converted = Translate::Trans($data, "UTF-8", "ISO-8859-2");

To also convert array keys, pass the recode_array_keys option:

$converted = Translate::Trans($data, "UTF-8", "ISO-8859-2", ["recode_array_keys" => true]);

Transliteration to ASCII

echo Translate::Trans("Příliš žluťoučký kůň", "UTF-8", "ASCII");
// → "Prilis zlutoucky kun"

The language option resolves conflicts between transliteration rules for different languages. Default is Slovak (suitable for Czech and Slovak texts).

// Slovak (default): ä → a
echo Translate::Trans("mäso", "UTF-8", "ASCII");
// → "maso"

// German: ä → ae
echo Translate::Trans("Jäger", "UTF-8", "ASCII", ["language" => "de"]);
// → "Jaeger"

Accepted language values: "sk", "sk_SK", "de", "de_DE", "DE", "en", etc.

Case conversion

echo Translate::Lower("PŘÍLIŠ", "UTF-8");        // → "příliš"
echo Translate::Upper("žluťoučký", "UTF-8");     // → "ŽLUŤOUČKÝ"

echo Translate::Lower("PŘÍLIŠ", "ISO-8859-2");   // works for 8-bit encodings too
echo Translate::Upper("žluťoučký", "Windows-1250");

Checking encoding

Returns true if the string is valid in the given encoding, false otherwise.

Translate::CheckEncoding($string, "UTF-8");   // → true / false
Translate::CheckEncoding($string, "ASCII");   // → true / false

Also works with arrays (checks all keys and values recursively):

Translate::CheckEncoding(["key" => "value", ...], "UTF-8");

An optional third argument lists forbidden byte sequences:

Translate::CheckEncoding($string, "UTF-8", ["\r\n", "<script"]);

String length

Returns the number of characters (not bytes) for multi-byte encodings:

$len = Translate::Length("Příliš", "UTF-8");   // → 6
$len = Translate::Length("Prilis", "ASCII");   // → 6

Supported encodings

Charset names are case-insensitive.

Using iconv

By default, the class uses its own conversion tables. If you are confident that iconv works correctly on your system (verify by running the test suite), you can enable it for better performance:

define("TRANSLATE_USE_ICONV", true);

Testing

Translate is tested automatically via GitHub Actions across PHP 5.6 to PHP 8.5.

Tests use the atk14/tester wrapper for phpunit/phpunit.

Install development dependencies:

composer update --dev

Run the test suite:

./vendor/bin/run_unit_tests test

License

Translate is free software distributed under the terms of the MIT license.