commit 2db9f7c4a1f231924220d834a3a85dd8e9607342 Author: Lorenzo Cogotti Date: Wed Aug 10 17:23:18 2022 +0200 [*] Initial commit. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0157472 --- /dev/null +++ b/.gitignore @@ -0,0 +1,46 @@ +# ---> Lua +# Compiled Lua sources +luac.out + +# luarocks build files +*.src.rock +*.zip +*.tar.gz + +# Object files +*.o +*.os +*.ko +*.obj +*.elf + +# Precompiled Headers +*.gch +*.pch + +# Libraries +*.lib +*.a +*.la +*.lo +*.def +*.exp + +# Shared objects (inc. Windows DLLs) +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app +*.i*86 +*.x86_64 +*.hex + +# ldoc output directory +doc/ + + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e9fd669 --- /dev/null +++ b/LICENSE @@ -0,0 +1,17 @@ +Copyright (c) 2022 The DoubleFourteen Code Forge + +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. +3. This notice may not be removed or altered from any source distribution. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c3a49b0 --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +moonspeak - Basic message localization library for LÖVE +======================================================= + +**moonspeak** is a basic internationalization library for +the [LÖVE](https://love2d.org/) engine. +It makes your game easy to translate into multiple languages. + +**moonspeak** does the following: + +* Loads dictionary files for your game. +* Allows selecting one of the many available languages. +* Translates messages by its id. + +Dependencies +============ + +**moonspeak** uses [df-serialize](https://git.doublefourteen.io/lua/df-serialize) +to read the dictionary file. + +**df-serialize** is also available on [LuaRocks](https://luarocks.org/modules/1414codeforge/df-serialize). + +Documentation +============= + +Code is documented with [LDoc](https://github.com/lunarmodules/LDoc). + +Documentation may be generated running the command: + +```sh +ldoc init.lua +``` + +`ldoc` outputs to a local `doc` directory, open `index.html` +with your favorite browser to read it. + +License +======= + +See [LICENSE](LICENSE) for details. diff --git a/init.lua b/init.lua new file mode 100644 index 0000000..64bf815 --- /dev/null +++ b/init.lua @@ -0,0 +1,109 @@ +--- LÖVE Localization Library +-- +-- Basic localization utilities, providing message translation +-- to multiple languages with fallback to English. +-- When package is first require()d, a default dictionary +-- is loaded from: assets/dict.lua +-- +-- A dictionary may also be loaded explicitly via loadDictFile(). +-- +-- @module moonspeak +-- @copyright 2022 The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti + +local serialize = require 'df-serialize' + +local moonspeak = { + --- (string) current locale language. + lang = "english" + --- (table|nil) current raw dictionary contents, as loaded by last loadDictFile(). + dict = nil +} + +--- Attempts to set a locale based on the current system settings. +-- +-- Fallbacks to 'english'. +function moonspeak.setDefaultLocale() + moonspeak.lang = "english" -- by default + + local lang = os.getenv("LANG") + + if lang ~= nil then + + local function startswith(s, p) return s:sub(1, #p) == p end + + if startswith(lang, "ja_") then + moonspeak.lang = "japanese" + elseif startswith(lang, "it_") then + moonspeak.lang = "italian" + elseif startswith(lang, "fr_") then + moonspeak.lang = "french" + end + end +end + +--- Load dictionary from file and set it as the current message source. +-- +-- In general there is no need to call this function explicitly, as a +-- default dictionary file is automatically loaded upon require(). +-- +-- A dictionary file is a file containing a regular Lua table containing +-- key-message pairs. +-- +-- @usage +-- -- Dictionary file example: +-- { +-- ["Hello, World!"] = { +-- english = "Hello, World!", -- this can be omitted, as it's identical to key. +-- italian = "Ciao, Mondo!" +-- -- more translations... +-- }, +-- ["Hello, %s!"] = { -- message with string.format() arguments. +-- -- english = ..., -- not necessary, key is used as a fallback anyway. +-- italian = "Ciao, %s!" +-- }, +-- ["I am %d years old."] = { +-- -- english = ..., -- ditto. +-- italian = "Ho %d anni." +-- } +-- } +-- +-- @param name (string) dictionary file name. +function moonspeak.loadDictFile(name) + local data = assert(love.filesystem.read(name)) + local dict = assert(serialize.unpack(data, name)) + + moonspeak.dict = dict +end + +--- Translate message. +-- +-- A message is looked up inside dictionary using key 'id'. +-- If such message provides a translation string in the current locale, then +-- that translation is used, otherwise the 'id' itself is used as the default message string. +-- +-- The selected string is then format()ted, as if by string.format(), +-- forwarding any argument. +-- +-- @param id (string) key to be used for locale message lookup. +-- @param ... optional additional string.format() arguments. +-- +-- @return localized and formatted string. +function moonspeak.translate(id, ...) + local msg = rawget(moonspeak.dict, id) + local lang = moonspeak.lang + + if msg ~= nil and msg[lang] then + -- Found localized string. + return msg[lang]:format(...) + end + + return id:format(...) -- fallback to default +end + +-- Load default dictionary +if love.filesystem.getInfo("assets/dict.lua") then + moonspeak.loadDictFile("assets/dict.lua") +end + +return moonspeak diff --git a/moonspeak-scm-1.rockspec b/moonspeak-scm-1.rockspec new file mode 100644 index 0000000..116e961 --- /dev/null +++ b/moonspeak-scm-1.rockspec @@ -0,0 +1,21 @@ +package = "moonspeak" +version = "scm" +source = { + url = "git+https://git.doublefourteen.io/lua/moonspeak.git" +} +description = { + summary = "LÖVE game localization library", + homepage = "https://git.doublefourteen.io/lua/moonspeak", + maintainer = "The DoubleFourteen Code Forge ", + license = "zlib" +} +dependencies = { + "lua >= 5.2" + "df-serialize" +} +build = { + type = "builtin", + modules = { + ["moonspeak"] = "init.lua" + } +}