Scrappy Language is a localisation management library for Solar2D that enables you to localise your games without affecting your development flow.

Rather than creating files for each language and filling your source code with things like “STRING_HELLOWORLD” you can simply have “Hello, world!” written in plain text and let the system build the database for you.

As with all my plugins it is free to use however if you find it useful, and are able to, I’d appreciate a coffee.

Image Credit: texting by ProSymbols from the Noun Project.

Getting Started

There are multiple ways to include the library in your project, the simplest is probably via the plugin, as outlined below, however if you wish you can also access the source code.

Plugin

build.settings

---

settings =
{
    plugins =
    {
        ["plugin.scrappyLanguage"] =
        {
            publisherId = "com.scrappyferret",
            supportedPlatforms =
            {
                iphone = { url="https://plugins.scrappyferret.com/scrappyLanguage/iphone.tgz" },
                android = { url="https://plugins.scrappyferret.com/scrappyLanguage/android.tgz" },
                macos = false,
                win32 = false
            },
        },
    },
}

main.lua

---

require( "plugin.scrappyLanguage" )
Scrappy.Fonts:init( params )

Source Code

If you wish you to access the source code directly it is available on GitLab here.

You can then clone or fork it if you wish, or add the library as a submodule to your project with this command:

git submodule add https://gitlab.com/scrappyferret-libs/scrappy-language.git language

However you get the source code into your project, you will then need to include it and initiate it.

main.lua

---

require( "language.core" )
Scrappy.Language:init( params )

API

Scrappy.Language:init( params )

Initiates the library.

params ( table ) – Parameter table for the initiation.

---

Scrappy.Language:get( name, language )

Gets a translated string from the database.

name ( string ) – The name of the text.

filename ( string ) – The name of the language.

returns – The translated text.

---

Scrappy.Language:change( name )

Changes the current language.

name ( string ) – The name of the langauge.

---

Scrappy.Language:list( )

Gets a list of all languages.

returns – A list of language names, empty if none registered.

---

Scrappy.Language:current()

Gets the name of the current language.

returns – The name of the language.

---

Scrappy.Language:build()

Builds all language files.

---

Examples

Initialise the system

Scrappy.Language:init
{
	supported = { "en", "fr", "de" },
	default = "en",
	format = "json",
	directory = "languages",
	rebuild = false,
	initialLanguage = "en",
}

Set up some strings in your code

-- Anywhere in your code, simply place the 'identifier' at the beginning and end of any strings that you wish to be marked as translatable.
local goodbye = "|Goodbye, world!|"

Building the string database

-- Call the build function, not in a production build!, to automatically scan your project for all translatable strings and output them to language files ready for translation.
Scrappy.Language:build()

After building you’ll get files much like this for each of your supported languages ( depending on your init params, you could also choose to have it outputted as a csv file rather than json )

en.scrappyLanguage

{"6cd3556deb0da54bca060b4c39479839":"Hello, world!","f6da94e9c2d5ac46e9e8ecee3a1731ff":"Goodbye, world!"}

Then just send them to whoever is localising your game so that they can do their magic, making sure they don’t alter the hashed identifiers. Note, please don’t use Google Translate like I have.

de.scrappyLanguage

{"6cd3556deb0da54bca060b4c39479839":"Hallo Welt!","f6da94e9c2d5ac46e9e8ecee3a1731ff":"Auf Wiedersehen Welt!"}

fr.scrappyLanguage

{"6cd3556deb0da54bca060b4c39479839":"Bonjour le monde!","f6da94e9c2d5ac46e9e8ecee3a1731ff":"Au revoir le monde!"}

Access the translated strings

-- Print the hello string in the current language
print( Scrappy.Language:get( "|Hello, world!|" ) )
-- Print the hello string in French
print( Scrappy.Language:get( goodbye, "fr" ) )
-- Change the language to German
Scrappy.Language:change( "de" )
-- Print the hello string in the current language
print( Scrappy.Language:get( "Hello, world!" ) )
-- Set the language back to English
Scrappy.Language:change( "en" )
-- Print out a greeting, passing in arbitrary values to be swapped out.
print( Scrappy.Language:get( "|My name is <> and I am <> years old.|", nil, "Graham", 34 ) )