Introducing Ordbok - An open source localization library for SketchUp Ruby Extensions



After some weeks of passive thinking and some days of tinkering I’m ready to announce a half-baked version of Ordbok, a localisation library for SketchUp extensions.

I think a lot of people are quite frustrated about LangHandler, both it’s unusual style and lack of features. There has been other attempts to localization in the past, e.g. @thomthom’s Babelfish (wish is where I learned string interpolation from).

This library aims to take SketchUp extension localization one step further, with features inspired by rails/l18n.

Some notable features are:

  • String interpolation
OB =
OB[:message_notification, count: 14]
# => "You have 14 new messages."
  • Simple pluralization rules
    (Pick different phrases based on count)
OB =
OB[:message_notification, count: 1]
# => "You have 1 new message."
# Note 'message' being in singular!
  • Phrase grouping
    (Required for pluralization)
OB =
OB["errors.file_missing", count: 1]
# => "Could not perform operation.\n\n1 file is missing."

The library is also built around descriptive keys, rather than full English strings, which both makes the code more readable and prevents translation errors due to homonyms in the source language(different phrases that just happens to spell out the same).

The library is not 100% finished but ready to be tested out. Enjoy!


Documentation is now available at


The lib has also ben updated today to let end users select language (if the extension developer decides to expose the option) and to save the language preference between sessions.


Hi, I am having trouble understanding what this library is used for… Can you explain it in layman is term?

Thanks and keep the good work!


Thanks for asking

It’s used to pull in text strings from external, localized (translated) files. This allows for adding multiple languages to an extension. SketchUp is shipped with LangHandler that also does this, but without fancy features such as string interpolation and pluralization.


I need to look into this because when I see my analytics of who buys my extensions I see people from all over the globe.

What would be the best way to have the users themself update their native languages into the extension?

I’ve seen game developers use Excel Spreadsheet to handle multiple languages because it makes it easy for everyone to edit.

Anyways, you’ve picked my interest with this and I’ll look into it more. Thanks!


I haven’t decided on the format yet. For now translations are stored in JSON files, which allows for nested keys.

Spreadsheets could be useful, especially as it allows translators/users to see the phrase in several languages at once. However there may be different number of phrases in different languages. In English (and most other germanic languages nouns (and sometimes other words) have a singular and a plural form, meaning you’d need to specify the phrases “There is 1 new message” and “there are X new messages” separately (unless you can stand writing “is/are” and “message(s)”). Some languages, like Russian, have more grammatical numbers, requiring more phrases to be specified. In a spreadsheet there would therefore rows that don’t apply to all languages, which may look odd and be confusing.

Anyhow, the format the strings are saved in inside of the plugin and the format used when writing the translations don’t need to be the same. As long as both are clearly specified you can always convert between them.

I’m thinking about either use Google Docs (spreadsheet) or a public GitHub repo for my translations when making localized extensions in the future, but haven’t decided yet.


Excel is certainly not professionally used for this (probably as a workaround to involve people who are just familiar with Excel). It is the input “form” that these developers convert into their translation files.

In any case, a process that can be automated (by a script) is ideal. This saves manual work and can be repeated endless times without human intervention (continuous integration).

There are also collaborative localization tools, either by the usual open source suspects (1, 2, 3) or for general purpose, like zanata and weblate. Apart from .po files they also support some JSON formats. It is also interesting that there exists already a JSON format used by Firefox and Chrom(e|ium) extensions.


I have scripts that scrape my Ruby, JS and HTML sources for strings to be localised. Using static analysis libraries I parse the AST of both Ruby and JS to reliably extract the strings. The strings are collected into a single source file which another script uploads to CrowdIn. A third script is then run whenever I need to update the strings from CrowdIn. That’s been working very well - especially since services like CrowdIn allows you to upload screenshots of where the various strings are used. Makes it easier for me as well as the translators.