g18n

A small, platform-agnostic translation library for Gleam webpages.

Installation

gleam add g18n

Quick start

Keep one JSON file per language and load the file selected by your application:

{
  "page": {
    "title": "Welcome",
    "greeting": "Hello {name}!",
    "navigation": {
      "home": "Home",
      "contact": "Contact"
    }
  }
}

import g18n

pub fn translations(json_source: String) {
  let assert Ok(strings) =
    g18n.translations_from_nested_json(json_source)
  let translator = g18n.new_translator(strings)
  let params =
    g18n.new_format_params()
    |> g18n.add_param("name", "Alice")

  g18n.translate(translator, "page.title")
  // "Welcome"

  g18n.translate_with_params(translator, "page.greeting", params)
  // "Hello Alice!"
}

Your application decides which language file to load. g18n only stores and looks up its strings; it does not impose locale or language rules.

Lookup behavior

Translations use dotted keys such as page.navigation.contact.

translate checks the primary translations and then optional fallback translations. If neither contains the key, it returns the original key. This makes missing strings visible without crashing the page.

let fallback =
  g18n.new_translations()
  |> g18n.add_translation("page.title", "Welcome")

let translator =
  g18n.new_translator(selected_language)
  |> g18n.with_fallback(fallback)

translate_with_params replaces supplied {parameter} placeholders. A placeholder without a value remains unchanged.

Adding translations in Gleam

let translations =
  g18n.new_translations()
  |> g18n.add_translation("page.title", "Welcome")
  |> g18n.add_translation("page.greeting", "Hello {name}!")

let translator = g18n.new_translator(translations)

Context-specific strings use the exact key@context convention:

let translations =
  g18n.new_translations()
  |> g18n.add_translation("open", "Open")
  |> g18n.add_context_translation("open", "file", "Open file")

let translator = g18n.new_translator(translations)
g18n.translate_with_context(translator, "open", g18n.Context("file"))
// "Open file"

JSON formats

Flat JSON stores dotted keys directly:

{
  "page.title": "Welcome",
  "page.greeting": "Hello {name}!"
}

Use translations_from_json and translations_to_json for flat JSON.

Nested JSON stores the same keys as objects:

{
  "page": {
    "title": "Welcome",
    "greeting": "Hello {name}!"
  }
}

Use translations_from_nested_json and translations_to_nested_json for nested JSON.

Development tooling

PO generation, source scanning, and translation analytics belong in the separately published g18n-dev package.

License

MIT