Language Adapter allows you to load strings in multiple languages based on packages you create, so your webpage is available in the languages you want with the phrases and words you chose. It is inspired by the principle of translating apps for Android and implements the principle very similarly in PHP. Among other things, LanguageAdapter supports automatic language detection (based on the Accept-Language HTTP header), country-specific language versions (e.g. en-US, which would be downgraded to en if en-US is not available) and a fallback language.
Install these files on any place you want. Simply include them by using php's include or require functions on any place you want to use them like this:
require 'path/to/language-adapter/languagePackage.class.php';
require 'path/to/language-adapter/languageReader.class.php';Before you use languageAdapter you need to define your language packages which languageAdapter will read. Follow these steps to create a directory from which languageAdapter will read its packages:
- Create a directory, name it as you want to but keep in mind you will need the path later in your code while initializing languageAdapter
- Create a directory inside the first one for each package you want to provide to languageAdapter and name it by there package name. You can use classic names like this: "en", or you can use complex package names like: "en-US" if you want to provide more details in your packages based on their region. Please Note: This is not a safe method, languageAdapter will work with the information the user's browser provides, these may not equal the actual the real geographic location of the user in some cases.
- Create a text-file (.txt) for each string you want to provide in their package folder. Name them like this: "stringId.txt". Replace stringId with any stringId you want to. Their content should be the string you want to provide for this stringId. You can skip this step if you want to define them programmatically as explained later in this README file.
- If you want to change some configuration for languageAdapter globally add a file named: "languagePackages.conf" to the main folder of containing your packages. These are the standard values, if you just want to use these you don't need to have a configuration file:
fallbackLanguage=en;
use_downgrade_fallbacks=1;
replace_linebreaks=1;
listen_on_get=1;
get_param=lang;
Please note their required values:
- fallbackLanguage: needs to be an existing package name
- use_downgrade_fallbacks: needs to be a boolean like 0 or 1
- replace_linebreaks: needs to be a boolean like 0 or 1
- listen_on_get: needs to be a boolean like 0 or 1
- get_param: needs to be a string
As well as their purpose:
- fallbackLanguage: is the language you want to fall back to if there is no other language available
- use_downgrade_fallbacks: is whether you want to downgrade complex package names to simple ones. If you choose "false", languageAdapter will use the package defined in "fallbackPackage" instead
- replace_linebreaks: is whether you want languageAdapter to replace linebreaks in strings with html "br" tags
- listen_on_get: is whether you want languageAdapter to listen on get parameters when choosing the language package
- get_param: the get parameter you want languageAdapter to listen on
Please note: If you don't want to overwrite their standard values just remove the property from your configuration file. languageAdapter will use their standard value instead.
languageAdapter supports linking a string in another string, it will replace your link with the string value found in the resource you linked. You can do linking like this:
String before your link @link:packageName/stringId string after your link
If you want to link a string included in the same package you can use the keyword "this" instead of a package name. This action will be faster and more efficient than linking the package name because the package doesn't need to load again. Here is a quick example:
String before your link @link:this/stringId string after your link
Before you use language-adapter you need to initialize it by creating a new reader like this:
$languageReader = new languageReader('path/to/languagePackages');Please note: You must specify the path from the perspective of languageAdapter, not from the script in which you include languageAdapter.
Example: Directory 1 contains these folders: languageAdapter and lang
In languageAdapter is the languageAdater library, while in lang are the packages. Then you have to specify the path "../lang", because from the point of view of languageAdapter the packages are located one folder above and in its subfolder lang.
Optionally if you want to change some settings at this point you can do it by this:
$languageReader = new languageReader('path/to/languagePackages', $fallbackLanguage, $use_downgrade_fallbacks, $replace_linebreaks, $listen_on_get);Note the types of these vars:
- $fallbackLanguage is a string. Its standard value is 'en' for English
- $use_downgrade_fallbacks is a boolean. Its standard value is true
- $replace_linebreaks is a boolean. Its standard value is true
- $listen_on_get is a boolean. Its standard value is true.
If you know the name of the package you would like to load do this:
$languagePackage = $languageReader->getLanguagePackage('packageName');If you'd not like to use the fallback package if this package doesn't exist, set the second argument to false like this:
$languagePackage = $languageReader->getLanguagePackage('packageName', false);Please Note: In this case this method will return false if the package doesn't exist.
If your packages contain an intranslatable package you can easily load it like this:
$languagePackage = $languageReader->getIntranslatablePackage();If you want to load the defined fallback package you can do this by this:
$languagePackage = $languageReader->getFallbackPackage();If you want to load the downgrade package of a complex language like this: "en-US" (the downgrade package is "en") you can get it by this code:
$languagePackage = $languageReader->getDowngradeLanguagePackage('complexLanguageName');languageAdapter provides an easy method to get the best package available for your user based on the "HTTP_ACCEPT_LANGUAGE" header of the user's browser, or (if not disabled in your configuration) using a defined languagePackage from a specified get parameter (standard is "lang"). languageAdapter will automatically find the package which fits the users needs most. You can load this package by doing this:
$languagePackage = $languageReader->getAutodetectedLanguagePackage();Please Note: If there is no package available listed in the user's "HTTP_ACCEPT_LANGUAGE" header and no package in your user's get parameters this method will return the fallback package
If you'd like to know which packages languageAdapter has detected use this method:
$languagePackageNamesArray = $languageReader->getPackageList();If you want to load every package languageAdapter has detected you can do it by this:
$languagePackagesArray = $languageReader->getPackages();You can get a string from a languagePackage by this method:
$string = $languagePackage->getString('stringId');If you want to print the string directly and not just get it you can do this by this:
$languagePackage->printString('stringId');Please note: This method won't return any value its a void method
If you'd like to set a new string or you'd like to overwrite it's old value you can do this by the following code:
$languagePackage->setString('stringId', 'stringValue');If you don't want to overwrite any value if this string exists, set the third argument to be false:
$languagePackage->setString('stringId', 'stringValue', false);If you'd like to get the name of a languagePackage you can get it by:
$languagePackage->getPackageName();