i18n.md

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

A common challenge for web developers is supporting multiple display languages for their web applications or websites. A traditional approach involves creating separate website paths for each language variant. For instance, a developer might use URLs like https://example.com/en/home for the English version and https://example.com/ar/home for the Arabic version.

WebFiori framework offers an alternative approach that utilizes a single URL to serve multiple language variants.

For example, https://example.com/home could dynamically render the content in English or Arabic based on user preferences or other factors.

Language Classes

For applications requiring multiple languages, developers must define language variables. This is achieved by creating language classes within the [APP_DIR]/langs directory.

• Language Class Naming Convention:

  • Each language class follows the naming format LangXX, where XX represents the two-letter ISO 3166-1 alpha-2 country code for the language.
  • All language classes must inherit from the base class Lang and reside within the [APP_DIR]\langs namespace.

• Default Language Classes:

  • The framework automatically generates two language classes by default:
    • LangAR - Arabic
    • LangEN - 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 LangUK. The class should be created in [APP_DIR]/langs.

Once the class is created, then the developer must make the class extends the class Lang. 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\Lang;

class LangUK extends Lang {
    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 Lang::createDirectory() can be used to create a directory and the method Lang::set() can be used to create a variable in a directory.

namespace app\langs;

use webfiori\framework\i18n\Lang;

class LangUK extends Lang {
    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 Lang::createAndSet().

namespace app\langs;

use webfiori\framework\Lang;

class LangUK extends Lang {
    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 Lang. 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 Lang::getLabel() to get a language variable.

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

class SampleService extends AbstractWebService {
    public function __construct() {
        parent::__construct('say-hello');
        $this->addRequestMethod('get');
    }
    
    public function processRequest() {
        
        $this->sendResponse(Lang::getLable('apis/say-hi'));
    }
}

Next: Global Constants

Previous: Background Tasks