Leaf Omniglot

Leaf Omniglot is a simple but powerful module that adds multi language capabilities to your leaf applications.

Installation

You can easily install Leaf Omniglot using Composer.

//: # () //: # ()

Quick Start Guide

Create translation folder and files

Initialize Omniglot

In your index.php file (if using MVC: public/index.php). Add these lines:

Add Language Switch Route

In your routes file ("_app.php" for MVC and "index.php" for base Leaf) add this line:

Start Translating

Now in your template file you can add the following:

(this example is using laravel blade as template engine but you can adjust according to your template engine)

Or in a simple index.php file

You should now see in your browser a dropdown with "en_US" as option and inside the "h1" tag the text: Hello World

You can now add another translation file with the same translation key but a different value
and see that the dropdown now has a new option and that you can click on it and switch language.

For example:

Now if you switch to "pt_PT" in the dropdown you should see the text: Ola Mundo

Basic Usage

After installing omniglot, you need to create a folder where your translation files will live. Inside this folder you create the files in the following way:

The important part is having a file suffixed with .locale.json the name for the language does not matter. You can use for example en.locale.json as well

Translation file content

Your translation files should have the following format:

As key in the json, you have the translation key, used to identify the translation and as value you have the translation itself in the language that you defined in the filename

Init

Initialize the module and pass your custom configuration

Configurations

These are the available configuration parameters that you can pass inside the init() method as seen above.

DEFAULT_LOCALE

With this parameter you define your default locale so that this is the initial locale used in your application load. The value configured here MUST match the translation file name that you define for this locale. Example:

TRANSLATION_FILES_LOCATION

As the name says, this is the path to the folder that contains the translation files, one suggestion would be: 'TRANSLATION_FILES_LOCATION' => './locales' and then put the translation files inside a locales folder.

LOCALE_STRATEGY

With this you defined the way that you want Omniglot to behave when fetching and storing the chosen locale. Possible values are: session, accept-language-header and custom.

• session: This is useful for a mvc/website setup. When you use omniglot and call setCurrentLocale or getCurrentLocale the current locale will be fetched/stored in session.
• accept-language-header: This is useful when you are using Leaf as an API only. You just need to set the Accept-Language header to the value of the locale that you want to use and omniglot will translate according to this locale. setCurrentLocale here won't do anything as in this use case only the external application that calls the API, sets the locale.
• custom: This is a more advanced option. Omniglot allows you to create your own locale fetching/storing strategy. To do this you need to create a class that implements LocaleStrategyPluginInterface. This interface has two methods:
  • getCurrentLocale(): This should return a string with the locale name.
  • setCurrentLocale(): And this is used to store the current locale (if needed). Does not return anything.

CUSTOM_LOCALE_STRATEGY_CLASS_NAME

After setting LOCALE_STRATEGY to custom and implementing your own class that implements the mentioned interface.
You set here the class name of your new class, example:

Available methods

tl()

This method you can call from anywhere in functional mode and is the main method for translating you strings. This method takes two parameters:

• key: The translation key defined in your translation files
• params: An array with the parameters that you define in your translation files, example:

omniglot()

This method allows you to use any method inside the Omniglot class. For example you could use omniglot()->translate() instead of tl(). The following methods are available under omniglot():

• omniglot()->init(): Explained above in the Basic Usage
• omniglot()->translate(): Same as tl()
• omniglot()->setCurrentLocale(): Used to set the current selected locale based on the chosen strategy
• omniglot()->getCurrentLocale(): Fetches current configured locale or the default locale in case nothing is configured yet
• omniglot()->getAvailableLocales(): Returns an array of locales available. This is fetched from the file names on the configured locales folder
• omniglot()->getDefaultLocale(): As the name implies, returns the configured default locale

omniglot()->addLanguageSwitchRoute()

You can call this method in the same file where you define your routes. For Leaf MVC / API that would be _app.
For a simple Leaf application it would be in index.php.

This will automatically create a POST route for you to call when you want to switch language.
You simply need to do a POST to /language/switch, with the following POST data:

``

And it will set this as current locale if the corresponding file exists. It will also redirect back to the page it was called from.

It also accepts 3 parameters.

• path: By default the defined path is /language/switch but you can pass any path you want
• requestLocaleParamName: By default the route is expecting POST data with a property called locale by default but this can be changed with this parameter
• redirectToReferer: By default this route will automatically redirect to referer but you can set this to false and then it will just return a simple json response

Links/Projects

• Leaf Docs