Internationalization

In this page:

• Introduction
• Language Classes
• Creating New Language Class
  • Adding Language Variables
• Using Language Classes
  • Using Language in Web Pages
  • Using Language in Web Services

Introduction

One of the things that might concern web developers is to offer their web application or website in more than one display language. One traditional approach is to have each language variant of the website in different path. For example, the developer might have a URL similar to https://example.com/en/home for English version and https://example.com/ar/home fore Arabic variant.

In WebFiori framework, it is possible to have one URL which points to multiple variants. For example, https://example.com/home can point to an English or Arabic variant of the website.

Language Classes

Before having same page in more than one language, developer must define his language variables. Language variables are defined using classes which exist in the folder [APP_DIR]/langs. Each language class will have the name LanguageXX where XX represents ISO 3166-1 alpha-2 country code of the language. Every class must extend the class Language and must be part of the namespace [APP_DIR]\langs.

By default, the framework will create two language classes in the directory [APP_DIR]/langs, the class LanguageAR for Arabic and LanguageEN for English.

Creating New Language Class

First step in creating new language class is to know its ISO 3166-1 alpha-2 code. Using that code, we create new class based on that code. Assuming that we would like to create a language class for UK. In this case, the name of the class will be LanguageUK. The class should be created in [APP_DIR]/langs.

Once the class is created, then the developer must make the class extends the class Language. After extending the class, the developer must specify writing direction of the language and its code in the constructor.

namespace app\langs;

use webfiori\framework\Language;

class LanguageUK extends Language {
    public function __construct() {
        parent::__construct('ltr', 'UK');
    }
}

We have just created new language class and it is possible to load it in our web application.

Adding Language Variables

Language variables are created in a way which is similar to having a directory. Inside the directory, you can have files and more directories. The variables represent the files in this case. The method Language::createDirectory() can be used to create a directory and the method Language::set() can be used to create a variable in a directory.

namespace app\langs;

use webfiori\framework\i18n\Language;

class LanguageUK extends Language {
    public function __construct() {
        parent::__construct('ltr', 'UK');

        $this->createDirectory('pages/home');
        $this->set('pages/home', 'page-title', 'Welcome to My Website');
    }
}

This approach can be used to create a single directory with a single variable. What if we would like to create multiple directories and variables? To achive this, the developer can use the method Language::createAndSet().

namespace app\langs;

use webfiori\framework\Language;

class LanguageUK extends Language {
    public function __construct() {
        parent::__construct('ltr', 'UK');

        $this->createAndSet('pages', [
            'home' => [
                'title' => 'Welcome to My WebSite',
                'description' => 'Home page.'
            ],
            'about' => [
                'title' => 'About Me',
                'description' => 'Information about the author of the website.'
            ]
        ]);
        $this->createAndSet('apis', [
            'say-hi' => 'Hi!'
        ]);
    }
}

This code will create a directory with name pages/home with two variables and a directory with name pages/about with also two variables.

Using Language Classes

After creating language classes and setting variables, they must be loaded for use in your APIs or web pages.

Using Language in Web Pages

The class WebPage has a method which can be used to get specific language variable. The method is WebPage::get(). The method accepts one parameter which is the path to language variable.

namespace app\pages;

use webfiori\framework\ui\WebPage;

class HomePage extends WebPage {
    public function __construct() {
        parent::__construct();

        $this->setTitle($this->get('pages/home/title'));
        $this->setDescription($this->get('pages/home/description'));
    }
}

By default, language of the page will be based on default website language. If ?lang=XX parameter is set in the query string, page language will be based on it.

Using Language in Web Services

Loading a translation in web services is performed directly using the class Language. It is possible to make the service send a response based on a language code by adding a get or post parameter with name lang or fall back to default language. The developer can use the static method Language::getLabel() to get a language variable.

use webfiori\http\Request;
use webfiori\framework\WebFiori;
use webfiori\http\AbstractWebService;
use webfiori\framework\Language;

class SampleService extends AbstractWebService {
    public function __construct() {
        parent::__construct('say-hello');
        $this->addRequestMethod('get');
    }

    public function processRequest() {

        $this->sendResponse(Language::getLable('apis/say-hi'));
    }
}

Next: Global Constants

Previous: Background Tasks