#moongettext

#Why this package?

• five PO comment classes: translator, extracted, reference, flag, previous;
• contexts, singular and plural entries, multiline strings, standard C escapes;
• obsolete #~ entries and fuzzy filtering;
• deterministic semantic PO/POT serialization;
• GNU MO revision 0 read/write in both byte orders;
• a C-like Plural-Forms parser with short-circuit and ternary evaluation;
• runtime gettext, pgettext, ngettext, and npgettext operations;
• explicit catalog fallback;
• validation, statistics, source-reference queries, and POT/PO merging.

#Install

moon add YanFangNie/moongettext

moon check --target all --deny-warn --warn-list +73
moon test --target all --deny-warn --warn-list +73
moon run examples/basic

#Quick start: parse and normalize PO

///|
test "parse and normalize a PO entry" {
  let source =
    #|#. Shown on the launch screen
    #|#: src/main.mbt:12
    #|msgctxt "button"
    #|msgid "Open"
    #|msgstr "Ouvrir"
    #|
  let document = @moongettext.parse_po(source)
  assert_eq(document.entries.length(), 1)
  assert_true(
    document.find_entry("Open", context="button") is Some(entry) &&
    entry.translation(0) == Some("Ouvrir"),
  )
  let reparsed = @moongettext.parse_po(@moongettext.write_po(document))
  assert_true(reparsed == document)
}

#Runtime lookup

///|
test "context and plural-aware lookup" {
  let document = @moongettext.PoFile::new([
    @moongettext.PoEntry::singular(
      "",
      translation=(
        #|Content-Type: text/plain; charset=UTF-8
        #|Language: fr
        #|Plural-Forms: nplurals=2; plural=(n > 1);
        #|
      ),
    ),
    @moongettext.PoEntry::singular(
      "Open",
      translation="Ouvrir",
      context="button",
    ),
    @moongettext.PoEntry::plural("file", "files", ["fichier", "fichiers"]),
  ])
  let catalog = @moongettext.Catalog::from_po(document)
  assert_eq(catalog.pgettext("button", "Open"), "Ouvrir")
  assert_eq(catalog.ngettext("file", "files", 1), "fichier")
  assert_eq(catalog.ngettext("file", "files", 3), "fichiers")
  assert_eq(catalog.gettext("missing"), "missing")
}

///|
test "fallback catalog" {
  let primary = @moongettext.Catalog::from_po(
    @moongettext.PoFile::new([
      @moongettext.PoEntry::singular("Hello", translation="Salut"),
    ]),
  )
  let fallback = @moongettext.Catalog::from_po(
    @moongettext.PoFile::new([
      @moongettext.PoEntry::singular("Open", translation="Ouvrir"),
    ]),
  )
  assert_eq(primary.gettext("Hello", fallback~), "Salut")
  assert_eq(primary.gettext("Open", fallback~), "Ouvrir")
  assert_eq(primary.gettext("Unknown", fallback~), "Unknown")
}

#MO compile and load

///|
test "compile and load big-endian MO" {
  let source =
    #|msgid ""
    #|msgstr "Content-Type: text/plain; charset=UTF-8\n"
    #|
    #|msgid "Save"
    #|msgstr "Enregistrer"
    #|
  let po = @moongettext.parse_po(source)
  let bytes = @moongettext.compile_mo_checked(po, endian=Big)
  assert_true(@moongettext.mo_endian(bytes) == Big)
  let loaded = @moongettext.Catalog::from_mo(bytes)
  assert_eq(loaded.gettext("Save"), "Enregistrer")
}

#Plural-Forms

1. primary values: integer, n, parentheses;
2. unary !, unary +, unary -;
3. *, /, %;
4. +, -;
5. <, <=, >, >=;
6. ==, !=;
7. &&;
8. ||;
9. right-associative ?:.

///|
test "Russian three-form expression" {
  let rule = @moongettext.parse_plural_forms(
    "nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;",
  )
  assert_eq(rule.select(1), 0)
  assert_eq(rule.select(2), 1)
  assert_eq(rule.select(5), 2)
  assert_eq(rule.select(21), 0)
}

#Validate a catalog

• metadata charset and Plural-Forms;
• duplicate context-aware keys;
• plural translation arity;
• embedded MO separator characters;
• fuzzy, obsolete, and untranslated entries;
• representative evaluation of plural rules for counts 0..=200.

///|
test "structured validation report" {
  let invalid = @moongettext.PoFile::new([
    @moongettext.PoEntry::plural("item", "", [""]),
  ])
  let issues = @moongettext.validate_po(invalid)
  assert_true(@moongettext.validation_has_errors(issues))
  let report = @moongettext.validation_report(issues)
  assert_true(report.contains("empty-plural-id"))
}

#Merge a POT template

///|
test "merge template with translated PO" {
  let template = @moongettext.PoFile::new([
    @moongettext.PoEntry::singular("Open"),
    @moongettext.PoEntry::singular("New"),
  ])
  let existing = @moongettext.PoFile::new([
    @moongettext.PoEntry::singular("Open", translation="Ouvrir"),
    @moongettext.PoEntry::singular("Old", translation="Ancien"),
  ])
  let merged = @moongettext.merge_template(template, existing)
  assert_true(merged.stats == { matched: 1, added: 1, obsoleted: 1 })
  assert_eq(merged.document.entries[0].translations[0], "Ouvrir")
  assert_true(merged.document.entries[2].obsolete)
}

#CLI

moon run cmd/main -- demo
moon run cmd/main -- validate examples/fr.po
moon run cmd/main -- normalize examples/fr.po
moon run cmd/main -- compile examples/fr.po _build/fr.mo
moon run cmd/main -- compile examples/fr.po _build/fr-be.mo --big-endian
moon run cmd/main -- inspect _build/fr.mo

moon run examples/basic

Ouvrir
0: fichier
1: fichier
2: fichiers
5: fichiers

#Main public API

#Compatibility and limits

• PO output preserves semantics, not original whitespace or line wrapping.
• MO revision 0 is supported; system-dependent revision extensions are not.
• MO strings must be UTF-8. Other declared charsets are reported.
• MO hash tables are accepted as header fields but ignored; emitted files use binary-search-compatible sorted original tables and no hash table.
• Advanced quoted source-reference filenames are retained as comment text but the convenience source_references tokenizer does not reconstruct them.
• This package does not extract translatable strings from MoonBit source and does not replace a translation-management platform.

#Project layout

model / escape               shared PO model and string escaping
po_parser / po_writer         semantic PO/POT codec
plural_lexer / plural_parser  Plural-Forms grammar and evaluator
mo_reader / mo_writer         strict MO revision 0 codec
catalog                       indexed runtime lookup and fallback
validation / query / merge    tooling APIs
cmd/main                      native file CLI
examples/basic                backend-neutral runnable example

#Development and release checks

moon version --all
moon fmt --check
moon info --target all
moon check --target all --deny-warn --warn-list +73
moon test --target all --deny-warn --warn-list +73
moon build --target native
moon run examples/basic
moon run cmd/main -- validate examples/fr.po
moon package --frozen
git diff --exit-code

#Specification and source notice

• GNU gettext PO Files
• GNU gettext MO Files
• GNU gettext Plural forms