Tutorial: How to change wording, How to change text, How to change language. How to change locale

peregrine · April 2014

How do I Translate or change a piece of text, is often asked on the forum

1. Finding Out What is Translatable via definitions/locales.

Generally anything in the core code or a plugin that is translatable will look like this

T("some piece of text!")

then all you need to do to change that text is to add a definition to one of your locale based files (see later explanation)

$Definition['some piece of text!'] = 'my changed piece of text';

notice how the left side of equation matches EXACTLY and the right side is your new translation or wording

if you see something like this

T('%s comment')

the %s stands for a string replacement. it must be included on the right side.

e.g. your definition could be any of the following

$Definition['%s comment']='%s Vietnamese post';
$Definition['%s comment']='my %s Vietnamese post';
$Definition['%s comment']='Spanish post %s';

notice the %s is on both sides of equation.

some definitions are not immediately recognizable. They may not have the words as you would think. Nevertheless they will be translatable.

e.g.

$Definition['GuestModule.Message'] = "It looks like you\'re either new here or you have not logged in yet. If you want to participate in our community discussions, click one of these buttons!";

another example in the code you might see the word Plural(

   echo '<strong>'.Plural($Discussion->CountUnreadComments, '%s New', '%s New Plural').'</strong>';

in this case...

you could change to completely get rid of the New designation.

$Definition['%s New'] = "";   
$Definition['%s New Plural'] = "";

or make it

$Definition['%s New'] = "%s Nuevo";   
$Definition['%s New Plural'] = "'%s Nuevo Plural";

the easiest way to get a list of almost all definitions is to download a locale addon. The language doesn't matter if you just want to get an idea of definitions used.

e.g.

http://vanillaforums.org/addon/browse/locales/popular/2/?Keywords=transifex

look in each of the files - some will have statements that start with

$Definition

these are your definitions.

You can also figure out definitions via

http://vanillaforums.org/addon/localedeveloper-plugin

So the idea is find out what is translatable either by looking at code and looking for T( statements
or looking at other locale plugins for definitions
or using the locale developer plugin.

If your forum is English based.

the easiest way to change definitions is via /conf/locale.php

you could change your /conf/locale.php by adding definitions to it.

e.g.

<?php if (!defined('APPLICATION')) exit();
$Definition['%s comment']='%s post';
$Definition['%s comments']='%s posts';
$Definition['Howdy, Stranger!'] = "Greetings, Bucko!";
$Definition['GuestModule.Message'] = "It looks like you\'re either new here or you have not logged in yet. If you want to participate in our community discussions, click one of these buttons!";

or you could add them to the bottom of the definitions file of your locale (e.g. Vietnamese locale)

locales/ViVN/definitions.php

Precedence of definition type files

the precedence is as follows for definitions

you change or add a definition in one of the following files

the order of locales (the higher the number on the list, the higher precedence).

en-CA is a country code (substitute your own country code that you use

~~~

1 - application based and dashboard based definitions
applications/locale/en-CA/definitions.php
applications/dashboard/locale/en-CA/definitions.php
2- plugin based - plugins/yourplugin/locale/en-US.php
plugins/your plugin/locale/en-US/definitions.php
3 - theme based - themes/yourtheme/locale/en-CA.php
4 - locale based - /locales/en-US/definitions.php
5 - locale based locales/en-US/other_definitions.php
6- conf based - conf/locale.php
7- conf - specialized conf/locale-en-US.php

~~~

so if you have a definition in this file

e.g.

applications/locale/en-CA/definitions.php

$Definition['Howdy, Stranger!'] = "Greetings, Bucko!";

and you have a definition in

conf/locale.php

$Definition['Howdy, Stranger!'] = "Greetings, Earthling!";

the Greetings, Earthling! will take precedence because

conf based file (conf/locale.php) is a higher precedence than applications (applications/locale/en-CA/definitions.php)

gotcha

Another thing to note if you have multiple duplicate definitions in the same file

e.g.

the last duplicated left hand side of the definition will rule.

another gotcha

if the Definition is like this

$Definition["You Can't do this"] = 'You Can't do this is bad - because the quoting is wrong';  // BAD
$Definition["You Can't do this"] = "You Can't do this is good - because the quoting is right";  // GOOD


$Definition['You "Can" do this'] = "But You "Can" not do this";  // BAD
$Definition['You "Can" do this'] = 'But You "Can" not do this';   // GOOD

the gist is if you have a single quote in your definition escape it or wrap it in double quotes
the gist is if you have a double quotes in your definition escape it or wrap it in single quotes

Troubleshooting

when modifying locales or adding locale files - always clear the ini files in the /cache folder - for best results.

to see if you are reading the files you think you are reading for locales.

look at the contents of

cache/locale_map.ini

if your locale file is not listed you are not reading it !

so if the cache/locale_map.ini

has this

****cache/locale_map.ini ****

0 = "public_html/forum/locales/ViVN/definitions.php"

and you are wondering why your definitions in conf/locale.php are not being read, it is because you need to delete the
cache/locale_map.ini

Mobile

you can also do mobile specific defintions... see

http://vanillaforums.org/discussion/25641/how-to-tutorial-theme-specific-definitions-mobile-vs-non-mobile

you can also see localization

http://vanillaforums.org/docs/localization

hgtonight · April 2014

This is an excellent write up!

I just want to mention 2 things. First, you don't have to include any %s in the right side of a definition if you want to disable the "dynamic" aspect of it.

Secondly, the /conf/locale.php file can be used regardless of your forum's language. In my mind, this is the file to change the wording of something slightly (like comments to posts in your example). So you can use it in addition to any other locale if you don't like what it says.

peregrine · May 2014

if it is not already obvious.

you can create a conf/locale.php

all you need in /conf/locale.php

is

<?php if (!defined('APPLICATION')) exit();

//then add any defintions you want.

x00 · May 2014

%s and the like are being superseded by ${NamedVariable}

I guess another tutorial is how to make addons locale friendly.

x00 · May 2014

Sorry I meant {NamedVariable}

peregrine · June 2014

this is a pretty good tool (r_j wrote it) for collecting probably all the possible translateable statements in vanilla in one spreadsheet.

downlad the t5.zip in the link below

and change the $path = 'Y:\temp\v21';

on line 4 to reflact the absolute path of your vanilla installation

e.g. yours might /var/www/vanilla

or publlic_html/yourname//vanilla or whatever.

or you could change line 4
to

$path = getcwd();

and drop the program in your vanilla folder and run www.example.com/vanilla/c5.php

assuming your folder is in vanilla.

http://vanillaforums.org/discussion/26793/translation-candidate

peregrine · June 2014

one more example for people for some of the semi-tough definitions that people have continual problems with.

Comment and View headings vs comment and view count.

    $Definition['%s view html'] = '%s Lượt xem';     // view count
    $Definition['%s views html'] = '%s Lượt xem';    // view count
    $Definition['%s comment html'] = '%s Trả lời';
    $Definition['%s comments html'] = '%s Trả lời';
   $Definition['Views'] = "mylittleviews";                  //view heading

$Definition['Comments'] = "mybigcomments";

peregrine · November 2014

plugin based locale information.

(if you don't want to use /conf/locale.php for your plugin definitions).

look in the language locale that you downloaded.

Actually things have changed a bit in locales, and it is a bit of a moving goal post. as far as naming conventions. but ... in vanilla 2.1.5

here is the trick to locales for plugins...

you need to look in the definitions.php file of the locale that you downloaded.

example the russian locale....

e.g. in http://vanillaforums.org/addon/vf_ru__petr1708-locale/definitions.php as of today.

    <?php

         $LocaleInfo['vf_ru'] = array (
          'Locale' => 'ru',
          'Name' => 'Русский / Russian',
          'Description' => 'Official Russian language translations for Vanilla. Help contribute to this translation by going to its translation site <a href="https://www.transifex.com/projects/p/vanilla/language/ru/">here</a>.',
          'Version' => '2014.11.01p1142',
          'Author' => 'Vanilla Community',
          'AuthorUrl' => 'https://www.transifex.com/projects/p/vanilla/language/ru/',

notice the name here

'Locale' => 'ru',

you can also find out easily what to use for a plugin, by looking in the cache/locale_map.ini

e.g.

[ru]
0 = "/var/www/vanilla/plugins/timeago/locale/ru.php"
1 = "/var/www/vanilla/locales/vf_ru/dash_core.php"
2 = "/var/www/vanilla/locales/vf_ru/definitions.php"
3 = "/var/www/vanilla/locales/vf_ru/missing.php"
4 = "/var/www/vanilla/locales/vf_ru/site_core.php"
5 = "/var/www/vanilla/conf/locale.php"

notice the [ru] - that is the locale name that you need for the plugin based locales.

so for timeago plugin for the above russian locale. you would name your file in the plugin to match the name of the locale in the brackets i.e. [ru]

/plugins/timeago/locale/ru.php

after you create a new locale file in your plugin.

to make the changes take effect.

either

go to the locales page in dashboard and save the russian (or what language you want) locale as your default locale.

that will force the locale_map.ini file to re-read all plugin based locales.

or

alternatively, you can also delete the cache/locale_map.ini file

peregrine · November 2014

if you still don't know the definition to use.

this may be helpful - you can search in these files and add them as needed to locale.php when making a change to a definition

remember do not change the part to the left of the = sign, the part you want to change is on the right side of =

e.g. if you see

$Definition['Welcome Aboard!'] = 'Welcome Aboard!';

change the wording on the right like so

$Definition['Welcome Aboard!'] = 'Glad to Have Ya';

definitions here

https://github.com/vanilla/locales/blob/master/tx-source/dash_core.php

https://github.com/vanilla/locales/blob/master/tx-source/site_core.php

peregrine · November 2014

@jackmaessen said in another discussion:
Well i read the article and i already did it that way. Per example, i put this line:
$Definition['Your password must be at least 6 characters long.'] = 'Wachtwoord moet uit minimal 6 karakters bestaan.'; in conf/locale.php and also in applications/dashboard/locale/en-CA/defenitions.php but no result.
he doesn't translate it.

I don't think you understand. that you can't guess. you need to find the actual definition.

there are several ways to find the definition.

one of which is

http://vanillaforums.org/discussion/26793/translation-candidate

instead of a crystal ball guess.... try...

$Definition['Your password must be at least %d characters long.'] = "Ze passworden musta be at leasta %d characters long.";

unless you are using en-Ca as your locale nothing in there will be used.

Also you might want to consider, anything you add to en-Ca will be overwritten anyway. and anything you add to your locale will be overwritten next time you download the transifex.

so your specific changes are better put in /conf/locale.php

jackmaessen · November 2014

Finally, it works. thanks; it should have been %d
But that's the whole problem everytime, you must find the exact text; one dot missing or one letter wrong; it doesn't translate it anymore. That's everytime a lot of searching where the text is being parsed. Actually, it should have been easier: tranlsate just one word of the text and it should be translated.
And those country locales are far away from complete.

@peregrine i already told that this was the wrong place to ask this question. But i am not been able to delete my own discussion anymore. So starting the same discussion in another category is kind of overkill. Ofcourse i can start the same discussion into another category but then there are 2 the same discussions

jackmaessen · November 2014

.

jackmaessen · November 2014

yet another problem with translation: ( i feel bad asking this again, but i can not fix it myself)
It is about the words: Too Short, Weak, Very Weak etc in the registration form. I found these words in global.js in the js folder.
The code looks like this:

// password strength check
   gdn.password = function(password, username) {
    var translations = gdn.definition('PasswordTranslations', 'Too Short,Contains Username,Very Weak,Weak,Ok,Good,Strong').split(',');

Even when i try to change these words in global.js itself, they are not being translated.
I emptied the .ini files in the cache folder, emptied browser cache but no result.
When i disable the var translations, these words don't appear anymore in the form; so it proves i am in the right file.
How is this possible? Why is translation impossible for this?

vrijvlinder · November 2014

Only words or sentences that have a T('translate me') can be translated via locale.

var translations = gdn.definition('PasswordTranslations', T('Too Short,Contains Username,Very Weak,Weak,Ok,Good,Strong')).split(',');

jackmaessen · November 2014

yes i agree with you @vrijvlinder, but i am not translating them in locale.php
I am trying to translate them in the file itself, but even that doesn't work. Very strange.
As far as i know, in global.js is the only place where those words appear
And when i change it the way you mention above (with T before it), the validation doesn't work anymore

vrijvlinder · November 2014

No, they also appear in the class.usermodel.php

public function AddPasswordStrength($Controller) {
      $Controller->AddJsFile('password.js');
      $Controller->AddDefinition('MinPassLength', C('Garden.Registration.MinPasswordLength'));
      $Controller->AddDefinition('PasswordTranslations', T('Password Translations', 'Too Short,Contains Username,Very Weak,Weak,Ok,Good,Strong'));
   }

peregrine · November 2014

you are not searching jackmaessen!!!!! or paying attention, read the comments again.

I've got two questions for you?

Do you know what spreadsheets are and can you run them?
if not, try to learn how to use a spreadsheet.

then re-reread a few time....

and see http://vanillaforums.org/discussion/26793/translation-candidate

@vrijvlinder said: Only words or sentences that have a T('translate me') can be translated via locale.

Not True. actually there are other Translations besides T, BigPlural, Plural

$Definition['Password Translations'] = 'Too Short,Contains Username,Very Weak,Weak,Ok,Good,Strong';

too

$Definition['Password Translations'] = 'Too Shortworden,Containen Usernamen,Very Weakling,Weaker, Perfecto,Bueno,Fuerte';

here is an attached file different text info for definitions in vanilla 2.16

you need to change the lines to the correct Definition format - but it will list pretty much all translatable things in the core and a few other plugins.

peregrine · November 2014

@jackmaessen

yes i agree with you @vrijvlinder, but i am not translating them in locale.php I am trying to translate them in the file itself, but even that doesn't work. Very strange. As far as i know, in global.js is the only place where those words appear And when i change it the way you mention above (with T before it), the validation doesn't work anymore

you should change locale.php - if you don't want things overwritten, and you haven't created your own custom locale. Read this line 10 times.

well, then YOU are doing the absolute WRONG thing then. Don't change the core and pay attention to the comments. Read this line 100 times.

jackmaessen · November 2014

@peregrine Normally i never change things in the core files, but i experienced with the $Defenition and to translate it but all didn't work.
I tried this:
$Definition['Too Short,Contains Username,Very Weak,Weak,Ok,Good,Strong'] = 'Te Kort,Bevat Gebruikersnaam,Erg Zwak,Zwak,OK,Goed,Sterk';
But that did not work.
So finally i tried to translate it in the file itself, and i found these words in global.js
But i did not know that these words also where in class.usermodel.php

I do not know how i can find words in all those thousends of files in vanilla. It is a disaster to search for them.
and no, i do not know about spreadsheets what you mention

peregrine · November 2014

funny the definition works absolutely perfectly for me in locale.php

please start from the top of this discussion thread.
spend 20 minutes reading. and you will get it correct.
then re-read it again.

it will save you 20 minutes of debugging, if you understand the concept and pay attention to the notes.

also re-read 1,000,000,000 times.
http://vanillaforums.org/discussion/comment/220473/#Comment_220473

Perhaps when you incorrectly modified core you cause problems.

vrijvlinder · November 2014

To find words simply enter them in the search field of the finder in the mac or equivalent in some other system.