Languages and Translations

This page is about how to with different languages and translations in Kiwa.

Table of contents

Language versions of pages

Because of its file-based logic, Kiwa can easily handle different language versions of pages. Let's assume we want to have an imprint in English and German. Our config would look like that:

<?php

$configGenerator
    // The english version
    ->addPage(PageGenerator::create()
        ->setName('imprint')
        ->setLanguageCode('en')
        ->setFile('imprint')
        // More options are needed here but not important for this example.
    )
    // The german version
    ->addPage(PageGenerator::create()
        ->setName('impressum')
        ->setLanguageCode('de')
        ->setFile('imprint')
        // More options are needed here but not important for this example.
    )
;

Depending on the configuration of the URL structure, the example above creates two routes /en/imprint.html and /de/impressum.html. Both routes lead to the same file imprint.phtml. Because of that, Kiwa is able to create alternate links by its own. Read more about that in the section Search engine optimization.

Now we have a single page for the imprint, where we can add our HTML and the text:

<?php

use Kiwa\Language\Text;

?>
<section>
    <h1><?php echo new Text('Imprint'); ?></h1>
    <p><?php echo new Text('This is the imprint for my page...'); ?></p>
</section>

When requesting one of those two pages, Kiwa will correctly handle the language version and load the translation for the text.

Translating text

Kiwa provides a class that allows to detect and handle translatable text:

<?php

use Kiwa\Language\Text;

echo new Text('Hello World!');

Depending on the predefined language, Kiwa will search for a translation inside the /language folder.

Translations with placeholders

In some cases, placeholders are needed to add information at a later point. This can be done like that:

<?php

use Kiwa\Language\Text;

echo new Text('You have {{MESSAGE_COUNT}} new messages', [
    'MESSAGE_COUNT' => count($messages),
]);

Using message domains

You can define message domains with the third parameter:

<?php

use Kiwa\Language\Text;

echo new Text('Hello World!', [], 'messages');

Kiwa will now look for a file with that name, for example /language/de.messages.php.

Manually setting the language code

It is possible to decide the target language in every single call, too. Use the fourth parameter for the language code:

<?php

use Kiwa\Language\Text;

echo new Text('Hello World!', [], null, 'de-de');

Storing translations

In Kiwa, all translations are stored inside the /language folder. There is a php file for each language, containing an array. The array keys are always the original language and the array values the current translation.

<?php

// `/language/de.php`

return [
    'Hello World!' => 'Hallo Welt!',
];

The Kiwa Console provides some commands to handle these files:

  • translation:clear finds unneeded translations, where the source language is equal to the translation.
  • translation:sort sorts the translations alphabetically.
  • translation:unused:remove removes orphaned translations, where a source can't be found.

Adding and updating translations

Kiwa can add and update translations by its own. For this case, you can use the Kiwa Console translation:find-missing command. The following will happen:

  1. Kiwa searches all Text objects and shows a list with them.
  2. Kiwa can create language files and store the text inside them if you want.

Automatic translations

Kiwa can translate the existing text into the target languages automatically. This happens by using Google Translate. To connect with Google Translate, you need to have the stichoza/google-translate-php library installed.

Using the current language code

You can use the current language code using the CurrentLanguageCode class:

<?php

use Kiwa\Language\CurrentLanguageCode;

/** This will print something like `en-gb`. */
echo new CurrentLanguageCode();

You can also handle the language code in an object-oriented way:

<?php

use Kiwa\Language\CurrentLanguageCode;

$currentLanguageCode = new CurrentLanguageCode();
$languageCode = $currentLanguageCode->getCurrentLanguageCode();

/** This will print something like `en-gb`. */
echo $languageCode->getLanguageCode();

/** This will print something like `en`. */
echo $languageCode->getCountryCode();