About GBC Language Cabinet

GBC Language Cabinet is an easy to use way to display text in different languages. Simply specify which
languages you are supporting, create or import tables of translated text, and use a basic function call to return the text in the correct language.

Several options exist to make your life even easier:

  • Text can be created with embedded keys. During the getText call, parameters can then be passed via a table. The returning text will be formatted to replace the keys with the parameters you passed. See below for examples.
  • You can import a comma-delimited file or a json file containing your text (including embedded keys!) instead of using multiple addText calls.

Set Up

First thing to do, is to activate the plugin from the Corona Marketplace.

In your applications build.settings file, include the reference to the plugin:

Be sure to require the plugin in each module you need to manage your data:

 

Reference

GBCLanguageCabinet.addLanguage(language, languageKey)

language – full name of the language to add
languageKey – reference key to the language

Adds support for the specified language.

Example:

GBCLanguageCabinet.removeLanguage(languageKey)

languageKey – reference key to language

Removes support for the specified language.

GBCLanguageCabinet.clearLanguages()

Removes all language support. This basically resets the supported language table.

GBCLanguageCabinet.getLanguages()

Returns as table with the following information for all supported languages:

key – the reference key to the supported language
language – the full name of the supported language

GBCLanguageCabinet.getDeviceLanguage()

This is a helper function that will return the 2 character language code currently set on the device.

GBCLanguageCabinet.addText(key, entryTable)

key – the reference key to the text in various languages
entryTable – a table of table entries in the following format:

languageKey – reference key to the language, as defined in previous addLanguage call.
textString – the actual translated text string.

Example:

GBCLanguageCabinet.addTextFromFile(fileName, fileType)

fileName – the name of a comma-delimited file used to create a series of text entries.
filetype – Either “csv” for a comman-delimited file, or “json” for a json file.

Instead of adding multiple entries individually with the addText function, you can import a comma-delimited or json file of text strings.

When this function is called, the file specified is read and imported. In order for this call to be successful, the following must be true:

  • The file must be in the same folder as your Lua code… no subdirectories.
  • If using a comma-delimited file:
    • It must contain a header record containing reference keys.
    • The keys listed in the header record must have been defined during an addLanguage function call.
    • All entries in the comma-delimited file should be enclosed in parenthesis.
  • If using a json file:
    • The keys listed in each table record must have been defined during an addLanguage function call.

The following is a valid comma-delimited file that can be used for import:

The first line is the header line, and contains the keys for the rest of the file. Only the languages that have previously been enabled during an addLanguage call are imported.

The following is a valid json file that can be used for import:

Example:

Note that in this example, the German (“de”) text from the comma-delimited and file will not be imported since that language was not enabled with a previous addLanguage call. Also notice that the language keys (“en” in this example) must match in the addLanguage and addTextFromFile calls.

GBCLanguageCabinet.removeText(key)

key – Reference key to specific table of language strings

Removes all text associated with key.

GBCLanguageCabinet.clearText()

Removes all text entries.

GBCLanguageCabinet.getText(textKey, languageKey, params)

textKey – Reference key to the text entry in the language cabinet.
languageKey – Reference key to the language of the text you want.
params – list of optional parameters, in table format, to insert into the string.

This function will return a single text entry in a specific language you specify.

If the text string contains parameter placeholders, the string is formatted with the parameter values passed to it in that order. For more details on passing parameters, see below.

Example:

The output of the above code would be:

This is extremely useful for dynamic creation of text… you do not have to split apart and rebuild text strings to include values you need. This also supports the grammatical differences between languages. Notice the Spanish statement grammatically lists the object first.

This function will substitute a passed parameter into an embedded key until all keys are substituted, or until all parameters have been used.  An extra embedded keys not substituted with a matching parameter are returned as well.

To create a placeholder, surround a keyword with two hash symbols. The keyword can be any keyword you wish, since this is just for your reference.

Sample Code

A sample Corona SDK project, including code and test json and csv files, are located here:  GBCLanguageCabinetExample.

Below is some examples on how to use GBC Language Cabinet

%d bloggers like this: