Home › Wiki › Translating Buttons (How To)

Translating Buttons (How To)

Introduction

Buttons for Custom Buttons² have the option to be translated to other languages base on the browser's locale. This is a guide on how to add localizations to your buttons as well as nice tricks and information on getting your strings translated.

Basics

First your button needs to have the, this.properties object setup. So add to your button (near the top):

this.properties = {
  // this is where the strings go
};

Next, we need to add an object for any language we are adding inside of the this.properties object:

this.properties = {
  en_US:{
    // this is where the strings go
  },
};

notice that languages are represented by the browser's general.useragent.locale value where any instance of a hyphen (-) is replaced with an underscore (_)

For a list of general.useragent.locale values from different browsers have a look at: Language Codes

Now we add in our strings, these are properties inside of each language object:

this.properties = {
  en_US:{
    Print:       'Print',
    PrintP:      'Print Preview',
    Left:        'L',
    Right:       'R',
  },
  ja:{
    Print:       '??',
    PrintP:      '???????',
    Left:        '?',
    Right:       '?',
  },
};

Now we can call any of these terms from within the button by coding, custombuttons.getLocalString(this, "Print"); in the place of the term. The extension handles the rest.

Translating Button Labels

Doing this will change the label of the button upon initialization, dependent on language:

this.properties = {
  en_US:{
    Label:       'Print/Print Preview',
    Print:       'Print',
    PrintP:      'Print Preview',
    Left:        'L',
    Right:       'R',
  },
  ja:{
    Label:       '??/???????',
    Print:       '??',
    PrintP:      '???????',
    Left:        '?',
    Right:       '?',
  },
};
this.label = custombuttons.getLocalString(this, "Label");

Translating Help Section

To translate "Help" you need to do similarly to the label translation (above).

Add an attribute for "Help" in your object then add:

this.setAttribute("Help", custombuttons.getLocalString(this, 'Help'));

Easing Translation

Easier Handling of getLocalString Function

Typing out custombuttons.getLocalString(this, "YourString"); can get a bit tiresome everytime you wish to translate a string. For this reason we present this alternative method:

var cb=custombuttons,self=this;
function l(str) {
  self.properties = {
    en_US:{
      Print:       'Print',
      PrintP:      'Print Preview',
      Left:        'L',
      Right:       'R',
    },
    ja:{
      Print:       '??',
      PrintP:      '???????',
      Left:        '?',
      Right:       '?',
    },
  };
  var str = cb.getLocalString(self, str);
  return str
}

With this, simply typing l("Print") would return the correct string. Much easier to deal with when coding.

Handling Line Breaks

For the help section of buttons you may want to code something like:

Help:     'Some Very long sentence, Some Very long sentence, Some Very long sentence, \nSome Very long sentence, Some Very long sentence, \nSome Very long sentence.'

Notice the \n's that were put in the string. This is "OK" but it could potentially make translation a bit confusing. For this reason we suggest the use of a function to add the line breaks to long lines. Add:

function splitLine(st,n) {var b = ''; var s = st;while (s.length > n) {var c = s.substring(0,n);var d = c.lastIndexOf(' ');var e = c.lastIndexOf('\n');if (e != -1) d = e; if (d == -1) d = n; b += c.substring(0,d) + '\n';s = s.substring(d+1);}return b+s;}

Then inside your l() function you can do something like:

var cb=custombuttons,self=this;
function l(str) {
  self.properties = {
    en_US:{
      Print:       'Print',
      PrintP:      'Print Preview',
      Left:        'L',
      Right:       'R',
      Help:        'Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence.'
    },
    ja:{
      Label:       '%1/%2',
      Print:       '??',
      PrintP:      '???????',
      Left:        '?',
      Right:       '?',
      Help:        'Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence, Some Very long sentence.'
    },
  };
  function splitLine(st,n) {var b = ''; var s = st;while (s.length > n) {var c = s.substring(0,n);var d = c.lastIndexOf(' ');var e = c.lastIndexOf('\n');if (e != -1) d = e; if (d == -1) d = n; b += c.substring(0,d) + '\n';s = s.substring(d+1);}return b+s;}
 
  var tstr = cb.getLocalString(self, str);
  if(str == "Help") tstr = splitLine(tstr, 48);
  return tstr;
}

Notice we simply just checked what attribute was requested and if it happened to be the "Help" attribute then we run it through the splitLine() function. You can change the length of the lines by altering the number 48 in the function.

String Replacements

Sometimes you may find it easier to simply concatenate two phrases together rather than making a translator translate the same string multiple times. Example:

var cb=custombuttons,self=this,lang=cb.getPref("general.useragent.locale");
lang = lang.replace("-", "_");
function l(str) {
  self.properties = {
    en_US:{      // English US translation by nicholas
      Label:       '%1/%2',
      Print_1:     'Print',
      PrintP_2:    '%1 Preview',
      Left:        'L',
      Right:       'R',
      Help:        ''
    },
  };
  var tstr = cb.getLocalString(self, str);
 
  // Operations to handle replacements
  if (tstr.match(/[%]\w{1}/g)) {
    lang = (typeof self.properties[lang] != "undefined") ? lang : "en_US";
    for(prop in self.properties[lang]) {
      if ((prop.match(/[_]\w{1}$/)) && ((prop.substr(prop.lastIndexOf("_")+1)) == (tstr.substring(tstr.indexOf("%")+1, tstr.indexOf("%")+2)))) {
        var tok = tstr.substring(tstr.indexOf("%"), tstr.indexOf("%")+2);
        tstr = tstr.replace(tok, l(prop));
      }
    }
  }
  return tstr;
}

Notice a few things here, first of all the first two lines:

cb=custombuttons,self=this,lang=cb.getPref("general.useragent.locale");
lang = lang.replace("-", "_");

The lang variable that was added, this is to retrieve what language is being called.

Then the property id's have _1 and _2 appended to them respectively. This is to indicate the this property is to be used as a replacement for all instances of %1 and %2 respectively.

The last thing is to be sure to include the provided function:

  // Operations to handle replacements
  if (tstr.match(/[%]\w{1}/g)) {
    lang = (typeof self.properties[lang] != "undefined") ? lang : "en_US";
    for(prop in self.properties[lang]) {
      if ((prop.match(/[_]\w{1}$/)) && ((prop.substr(prop.lastIndexOf("_")+1)) == (tstr.substring(tstr.indexOf("%")+1, tstr.indexOf("%")+2)))) {
        var tok = tstr.substring(tstr.indexOf("%"), tstr.indexOf("%")+2);
        tstr = tstr.replace(tok, l(prop));
      }
    }
  }

That's it, string replacements don't get much easier than that!

Get Your Strings Translated

Now that you know how to make your strings translatable, here is how/where to get those strings translated.

Where

You can get your strings translated in the subforum on Babelzilla's site which was made for us. Babelzilla Board -> Translation of Strings for Custom Buttons

How

There are two ways you can provide your strings.

Option Number 1

Create a new topic in the subforum with a title of this format

[BUTTON] Button Name

Paste your strings in as plain text between bbcode code tags.

    en_US:{             // English US translation by nicholas
      Label:              'Drupal Theme Switcher',
      Refresh:            "Refresh Theme's List",
      NOT:                'Your theme has NOT been switched, you may not be logged in!',
      HAS:                'Your theme has been switched! Now refreshing page...',
      Error:              'The theme may not have been submitted, there was an error',
      AddedMenu:          'The themes have been added to the menu',
      NotGetList:         'Could NOT get list of themes, you may not be logged in!',
      ChooseTheme:        'Choose a theme from the menu'
    }

The translators will then respond the same way.

Option Number 2

Create a new topic in the subforum with a title of this format

[BUTTON] Button Name

Then attach a simple .txt file (please stick to utf-8) on the top post with your strings to translate.

The translators will likely respond with a .txt file attached to their posts.

Posting your Translated Buttons

It is worthy to note that our site has a way of crediting users who supply translations and linking to the thread where users may submit translations. You may find this option under the tab "Languages"

Additionally, this site checks the browsers' useragent and if there is a BabelZilla Translation Thread listed for the button and there is not a matching translation for the posted button then the user will see some text along the lines of "[LANGUAGE] Not Available: Submit Your Translation Here". The text is translated to the browsers' language if we have the language available in our db. The "Submit Your Translation Here" string is hyperlinked to the BabelZilla Translation Thread.

Note: If you get English text for the above string (on the button posts) instead of your default language and you would like to see this string translated for your language please submit your translation here.