Babel is a module to enable internationalisation in Lua applications. It is designed to work with LÖVE 2D too.
Lua Shell
Latest commit 20b3234 Oct 12, 2016 @martin-damien Fix rockspec

README.md

BABEL

Build Status Coverage Status License

Babel is a simple internationalisation tool for Lua and LÖVE 2D.

Installation

Copy / Pasta

Simply copy babel.lua in your project folder wherever you want.

Then you will call babel with:

babel = require "your/path/to/babel"

Luarocks / from downloaded sources

Official repository submission is currently pending, but you can install babel with Luarocks this way :

Get the full code of babel using the autogenerated archive or by cloning the repository with git:

git clone https://github.com/martin-damien/babel

Then go in the babel folder with a terminal and type:

luarocks make

This will install babel as if it was downloaded from the official repository on your system.

Then you will call babel with:

babel = require "babel"

Luarocks / from official repository

In a terminal type:

luarocks install babel

The you will call babel with:

babel = require "babel"

Usage

Standalone applications

Standalone applications can use babel the way they want. Just take a look at the API and this short example:

-- We assume that our translations will be in a
-- "translations" folder at the root of our project.
-- (this is the default path)

babel.init({ locale = "jp_JP" })

print( _("Hello %name%", { name = "Kitty" }) )

NB: By default, the locale is the OS locale. If the OS locale cannot be found, the locale is set to "en_UK".

LÖVE games

Note that for LÖVE games you will need the Copy / Pasta installation to make it available trough your folder or your archive.

Initialisation

You must initialize babel in love.load().

function love.load()

    babel.init({
        locale = "fr-FR",
        locales_folders = { "assets/i18n", "assets/i18n/monsters" }
    })

end

API

Initialisation

babel.init() can get a table as argument with the following indexes :

  • locale The locale to use.
  • locales_folders A table of the folders where babel will look for locales files.

Translate text

There is two function to translate text : babel.translate and _ (who is a global alias to the first function).

_( "Text to translate" )
-- or
babel.translate( "Text to translate" )

Formating date and time

There is only one function for displaying date and time : babel.dateTime:

babel.dateTime( "long_date_time", os.date( "*t" ) )
babel.dateTime( "%H:%i:%s" )

The first parameter could be two things:

  • An index in the date_time table in the formats table of locale files.
  • A pattern to use

The second parameter is a table following the format returned by os.date (See documentation). If not provided, it will be set to the current date/time.

Symbols that can be used in custom patterns

  • %H: hour (on 24)
  • %i: minutes
  • %s: secondes
  • %g: hour (on 12)
  • %a: AM/PM
  • %d: day
  • %l: day name (long name)
  • %F: month name (long name)
  • %m: month
  • %Y: year (4 digits)

Formating numbers

There is two functions to format numbers : babel.number for simple numbers and babel.price for prices.

babel.price( 2340.90 )  --  £ 2,340.90
babel.number( -3400 )   --   -3,400.00

Using variables in translated texts

You can use variables in translations by passing extra parameters to the translate function :

_( "Hello %name%", { name = "your name" } )

You can use as many entries you need in the extra table.

Add locales files on the fly

If you need to load other locales files after init(), you can use :

babel.addLocalesFolder( "my other/folder" )

Change which locale to use

You can switch the current locale using:

babel.switchToLocale( locale )

Create and manage locale files

All the translations are stored in a lua file with the name of the locale (for ex. en-UK.lua or fr-FR.lua. Thoses files are stored in the folder given in babel.init() (or in a translations folder in the same folder than babel.lua if none given).

Structure of a locale file

LANGUAGE = {

    formats = {
        date_time = {
            my_format = "%l %H:%i"
        }
    },

    -- List of all the translations
    translations = {

        -- The key of each element is the text in parameter of babel.translate()
        ['Hello world'] = "Bonjour le monde",
        ['My name is %name%'] = "Mon nom est %name%"

    }

}
return LANGUAGE

Embedded languages presets

Babel embbed presets for some languages:

  • ar_SA
  • ca_ES
  • cz_CZ
  • da_DK
  • de_DE
  • el_EL
  • en_AU
  • en_CA
  • en_NZ
  • en_UK
  • en_US
  • eo_EO
  • es_ES
  • fi_FI
  • fr_FR
  • he_IL
  • hi_IN
  • hr_HR
  • hu_HU
  • id_ID
  • it_IT
  • jp_JP
  • ko_KR
  • nl_NL
  • no_NO
  • pl_PL
  • pt_BR
  • ru_RU
  • sk_SK
  • se_SE
  • sr_SR
  • tr_TR
  • uk_UA
  • zh_CN
  • zh_HK
  • zh_TW

NB: If you want to fix or add a preset for your language, please make a pull request :)