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:
- Kiwa searches all
Text
objects and shows a list with them. - 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();