A Lua implementation of Project Fluent, a localization paradigm designed to unleash the entire expressive power of natural language translations. Fluent is a family of localization specifications, implementations and good practices developed by Mozilla who extracted parts of their 'l20n' solution (used in Firefox and other apps) into a re-usable specification. For more information also see the Fluent Syntax Guide, the Discourse channel, documentation wiki, and playground.

Other implementations already exist in Rust, Javascript, Python, c#, elm, and perl. See also other implementations.

¹ _{Fluent the localization paradigm, not to be confused with Fluent the API interface concept!}

As of now it is possible to use this for simple string localization (without parameter substitution) but it is not feature complete nor is the API stable (see lua alternatives. If you have ideas about how the Lua API should work or wish to contribute, please join the project chat and/or open issues for points of discussion.

Added support for more types including format support for TextElement, StringLiteral, NumberLiteral, and VariableReference. Variable sutstitions can be done by passing a parameters table to format(). Internally manipulating nodes in the API is now easier with meta methods. For example merge comments with Comment + Comment, attach childred with Message * Comment, etc.

Massaged the AST returned by the PEG grammar so that about 1/3 of the possible types look like the reference Fluent spec. A basic Lua API is starting to take shape, modeled most closely to the Python implementation. It is possible to load and parse almost any FTL file, and possible to format any messages that are plain strings (no parameters, attributes, functions, or other jazz yet). Note there is no locale handling yet so it's only usable with separate instances per locale. Also add_messages() likely only works once, so cram your whole FTL resource in there for now.

Completed a PEG grammar based parser for the entire 1.0 Fluent file format spec. All the pieces are there, but it's only partially tested. It at least parses a few basic types of entries. The AST it returns is straight out of luaebnf and probably needs massaging to match the reference ones (via capture groups?), then it needs testing against the upstream fixtures.

Initialized project with some boiler plate Lua aparatus.

Lua code demo.lua:

local FluentBundle = require("fluent")
local en = FluentBundle("en-US")
en:add_messages({
    "foo = bar",
    "hello = Hello { $name }!"
  })
print(en:format("foo"))
print(en:format("hello", { name = "World" }))

Output of lua demo.lua:

bar
Hello World!

If you need something that works in Lua now, have a look at the already mature i18n.lua project (Github / LuaRocks). It implements many of the same features this project will, just without the interoperability with other Fluent based tools. The Lua API it provides is quite nice, but your localization data needs to be provided in Lua tables instead of FTL files. While Fluent has quite a few more tricks up its sleeve the i18n module already has working interpolation, pluralization, locale fallbacks, and more. And it works now, today.

Another even simpler solution is the Lua say module (Github / LuaRocks) from the makers of Busted. This is much closer to a flat one-to-one key value map, but with namespacing is such a way that it is useful for localization.

This project's end goal is to provide an idiomatic Lua API implementing the Fluent spec that is fully compatible with other FTL based tooling. This will allow Lua projects to easily implement localized interfaces with natural sounding translations and take advantage of tools such as Pontoon.