Documentation

Light-weight, fast, simple and powerful!
 

Translator Notes

Guidance of Wolf's i18n elements for Plugin developers. If you are a translator, please see the Translator Notes page.

Introduction

Wolf CMS has been designed to make “internationalization” (i18n), that is, translation of its administration and plugins, as simple as possible. In case you are wondering, “internationalization” is composed of an “i” followed by “18” letters and ended by an “n”, giving you “i18n”.

The following guidance and suggested procedures should help those who wish to allow their plugin to be translated by the community for wider acceptance and use among Wolf users.

Before you begin

  • Consult the Translator Notes to learn a bit more on the translation system available to Wolf Plugin Developers
  • Always ensure you are working with the most recent stable Wolf version.

Creating a basic translatable string

Anytime you have a word or sentence that needs to be translated, in the most basic form, simply encapsulate it in __() to let Wolf know that the string can be translated. For example:

echo __('Hello World');

would output:

Hello World

This works for the title and description of your plugin, which is defined in the index.php file in the root of your plugin directory. You can set your information to look like:

Plugin::setInfos(array(
    'id'          => 'plugin',
    'title'       => __('Plugin'),
    'description' => __('A plugin by any other name...'),
    'version'     => '1.2.3',
    'license'     => 'MIT', 
    'author'      => 'John Doe ' . __('and') . ' Jane Doe'
    ));

Note in the above example how “Plugin”, “A plugin by any other name…” and the word “and” are translatable, but the names “John Doe” and “Jane Doe” are not. For the majority of plugins, that's all you need to know!

Creating more advanced translatable strings

In some cases you may need to inject a variable into your translatable string. In this case you'll need to use a slightly more complex method to have your string show up the way you want.

An example that could be used:

Bobby is 10 years old.

That is your string, but you aren't sure of the name or the age of the subject, so you need to inject a couple of variables. To just turn it into the basic translatable string, you'd change it to read:

echo __('Bobby is 10 years old.');

The next step is to add your variables. The standard way to do so in Wolf CMS is like this:

$name = 'Bobby';
$age = 10;
 
echo __(':name is :age years old.', array(':name' => $name, ':age' => $age));


An alternative method would be to use the slightly more complex sprintf() and printf() PHP function. You might want to read up a bit on these functions.

If you've read the PHP documentation on both functions, you'll have an idea on how the sprintf function works. We'll be focusing only on sprintf() here, though printf is very similar. Like in our previous method, we'll use this example:

Bobby is 10 years old.

The next step is to add the PHP sprintf() command and insert your variables. You can co so like this:

$name = 'Bobby';
$age = 10;
printf(__('%s is %d years old.'), $name, $age);

As you've read in the PHP documentation, %s represents a string and %d represents an integer. This means you can only put a whole number in the %d spot. In the above example, $name refers to %s because %s is the first in the string and $name is the first defined variable after the string. For every variable you introduce into a string, you'll need to add another variable after the string.

Translating advanced translatable strings

Almost as important to creating and injecting variables into translatable strings, is the ability to move those variables around. Different languages have different rules regarding their grammar, and at some point it may become necessary to move one variable to another location. I don't speak any languages besides English, so I'm going to use two separate sentences and move the variables to show how it's done.

In this example:

Is that 10 year old Bobby?

We could ask a similar question by rearranging a few items to read:

Is that Bobby 10 years old?

Not completely grammatically correct, but it will get the idea across. We'll turn our first example sentence into a Wolf CMS standard translatable sentence and then translate it to create the second statement. Here's what our translatable string would look like:

$name = 'Bobby';
$age = 10;
 
echo __('Is that :age year old :name?', array(':name' => $name, ':age' => $age));

This creates a translatable string that is placed in a text file. If that was the only translatable string in your plugin, your blank translation file would look like:

<?php
    return array(
        'Is that :age year old :name?' => ''
    );
?>

Now you will want to make it display the second (“translated”) example statement, above. In order to do that, we're going to have to rearrange the order of the variables in the translated string. The translated string would look like:

<?php
    return array(
        'Is that :age year old :name?' => 'Is that :name :age years old?'
    );
?>

At this point, when Wolf CMS encounters the first statement, it would output the second “translated” statement in its place. The numbers signify which position the variable you are referring to is located after the string.

The end result would be that our “translation” reads:

Is that Bobby 10 years old?


An alternative method would be to use PHP's sprintf() or printf() functions. The following creates a translatable string that is placed in a text file:

$age = 10;
$name = Bobby;
printf(__('Is that %d year old %s?'), $age, $name);

If that was the only translatable string in your plugin, your blank translation file would look like:

<?php
    return array(
        'Is that :age year old :name?' => ''
    );
?>

Now you will want to make it display the “translated” version. In order to do that, we're going to have to rearrange the order of the variables in the translated string. The translated string would look like:

<?php
 
return array(
    'Is that %d year old %s?' => 'Is that %2$s %1$d years old?'
);
?>

At this point, when Wolf CMS encounters the first statement, it would output the second “translated” statement in its place. The numbers signify which position the variable you are referring to is located after the string. You could write your initial statement like this:

$name = 'Bobby';
$age = 10;
printf(__('%1$s is %2$d years old.'), $name, $age);

However, it's easier to read, and slightly shorter to type, if you use just ”%s”, instead.

Translating

Wolf's admin includes a translation template generator to help out translators with translating the Wolf core and plugins. Go to the Administration > Settings tab in Wolf's backend:

Admin Settings

Clicking on the “translate Wolf” link (circled in red in the image above) will take you to a page with complete instructions for doing your translation, as well as links which will generate the template files both for the Wolf core as well as for those plugins which have i18n implemented.

Updating your work

Keep in mind that anytime you change the text in your plugin, the i18n files may need to be updated to reflect the changes. Any changes made to your plugin, but not made to the i18n files by someone proficient in the language will show as untranslated to the general user. This means until an English plugin is updated to match your changes, translated items will continue to show up in their translated languages and anything else will show up in English.

 
tutorials/translating_plugins.txt · Last modified: 2011-09-12 00:46 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.2
Copyright 2010 wolfcms.org / design by yello studio / Wolf CMS Inside