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