-spec dump(parsed_catalog()) -> binary().

Serializes a parsed_catalog() back to PO text (a UTF-8 binary).

Emits the header block first (msgid "" / msgstr "" plus the header raw, or a minimal header Content-Type: text/plain; charset=UTF-8 when the raw is empty or absent) and then each entry. singular entries produce msgctxt/msgid/msgstr; plural entries re-emit the retained msgid_plural (finding #14 — when it is undefined, the singular msgid is used as a stand-in) and one msgstr[N] line per form. The strings are re-escaped (\\\\, \\", \\n, \\t, \\r) so that parse(dump(C)) preserves the catalog. A total function: it always returns a binary().

Parameter: Catalog must be a valid parsed_catalog() (#{header := _, entries := _}) — typically the {ok, Catalog} from parse/2. A map without the header/entries keys triggers function_clause (contract: it only consumes what parse/2 produces). Each entry() must have the singular/plural shape; a tuple of any other shape falls through dump_entry/1 and crashes.

The minimal synthetic header is NOT emitted with the Content-Type glued onto the msgstr line: dump_header_text/1 always emits msgstr "" and dumps the header body as quoted CONTINUATION LINES (encode_header_line/1). So the actual output for a catalog WITHOUT a header of its own is:

1> {ok, C} = erli18n_po:parse(<<"msgid \"Hi\"\nmsgstr \"Oi\"\n">>).
2> erli18n_po:dump(C).
<<"msgid \"\"\nmsgstr \"\"\n"
  "\"Content-Type: text/plain; charset=UTF-8\\n\"\n\n"
  "msgid \"Hi\"\nmsgstr \"Oi\"\n\n">>

WATCH OUT for the roundtrip: the .po above has no header, so C carries a synthetic header (raw => <<>>, content_type => <<>>). dump/1 injects a minimal Content-Type; on re-parse, that field is no longer empty, so the catalog differs from the original and equality is FALSE:

3> erli18n_po:parse(erli18n_po:dump(C)) =:= {ok, C}.
false

The law parse(dump(C)) =:= {ok, C} only holds for catalogs that ALREADY had a header of their own (raw =/= <<>>) — exactly the case of the quickstart in the moduledoc, which does return true.

Inverse path of parse/1 / parse/2. See parsed_catalog/0 and entry/0.

-spec parse(binary()) -> {ok, parsed_catalog()} | {error, parse_error()}.

Parses a PO catalog from a binary, with default options (include_fuzzy => false).

Equivalent to parse(Bin, #{}). Returns {ok, parsed_catalog()} with the normalized header and the list of entries (in file order), or {error, parse_error()} if the charset is invalid, the conversion fails, there is a syntax error, or the plural indices diverge from nplurals.

1> erli18n_po:parse(<<"msgid \"Hello\"\nmsgstr \"Ola\"\n">>).
{ok,#{header => #{charset => utf8,content_type => <<>>,
                  plural_forms => <<>>,raw => <<>>},
      entries => [{singular,undefined,<<"Hello">>,<<"Ola">>}]}}

See parse/2 for the full semantics of options and the pipeline, and dump/1 for the inverse path.

-spec parse(binary(), parse_opts()) -> {ok, parsed_catalog()} | {error, parse_error()}.

Parses a PO catalog from a binary, honoring Opts.

Bin is the raw content of the .po; Opts is a parse_opts() — today only include_fuzzy => boolean() (default false: entries marked #, fuzzy are dropped, parity with msgfmt). The flow: (1) silent strip of the UTF-8 BOM (PSD-005); (2) a prepass that extracts the charset from the Content-Type header via the same field reconciler as build_header/1, ensuring that prepass and builder never diverge (finding #5 — closes the badmatch on a Content-Type with a space before the :); (3) normalizes the entire body to UTF-8 in the discovered charset; (4) line-by-line parse with the charset threaded so \\xHH/\\OOO escapes are transcoded through the right code space.

Returns {ok, parsed_catalog()} (#{header => header_map(), entries => [entry()]}) or {error, parse_error()}. Without an explicit header, it synthesizes an empty header with charset utf8. Accepts LF, CRLF and lone-CR line endings (finding #15).

Parameters:

• Bin — raw content of the .po/.pot. Treated as UNTRUSTED: an nplurals= or msgstr[N] with an absurd run of digits is rejected in O(1) (cap by ?MAX_INT_DIGITS), never builds a bignum.
• Opts — see parse_opts/0. include_fuzzy controls whether #, fuzzy entries enter the result.

Failure modes (all {error, parse_error()}, never a crash): an unsupported declared charset, bytes that do not match the charset, plural indices that diverge from nplurals, and malformed lines (with line number).

1> Fuzzy = <<"#, fuzzy\nmsgid \"a\"\nmsgstr \"b\"\n">>.
2> {ok, C0} = erli18n_po:parse(Fuzzy, #{}).
3> maps:get(entries, C0).
[]
4> {ok, C1} = erli18n_po:parse(Fuzzy, #{include_fuzzy => true}).
5> maps:get(entries, C1).
[{singular,undefined,<<"a">>,<<"b">>}]
6> erli18n_po:parse(<<"msgid \"a\"\nmsgstr \"b\"\n???\n">>).
{error,{syntax_error,3,{unrecognized_line,<<"???">>}}}

See parse/1 (defaults), parse_file/2 (from disk) and dump/1.

-spec parse_file(file:filename()) -> {ok, parsed_catalog()} | {error, parse_error()}.

Reads and parses a .po file from disk, with default options.

Equivalent to parse_file(Path, #{}). Reads Path with file:read_file/1 and delegates to parse/2. Read errors become {error, {file_error, file_read_error()}}.

1> erli18n_po:parse_file(<<"priv/locale/fr/LC_MESSAGES/my_domain.po">>).
{ok,#{header => #{charset => utf8, ...}, entries => [...]}}
2> erli18n_po:parse_file(<<"/does/not/exist.po">>).
{error,{file_error,enoent}}

See parse_file/2 (with options) and parse/2 (the parse semantics themselves).

-spec parse_file(file:filename(), parse_opts()) -> {ok, parsed_catalog()} | {error, parse_error()}.

Reads and parses a .po file from disk, honoring Opts.

Reads Path with file:read_file/1; on success it delegates the binary to parse/2 with Opts (see parse/2 for the semantics of the options and the return). If the read fails, it returns {error, {file_error, Posix}}, where Posix ranges over file:posix() | badarg | terminated | system_limit.

Parameters:

• Path — file path, any file:filename().
• Opts — passed untouched to parse/2; see parse_opts/0.

The only difference from parse/2 is the read phase: I/O errors become {error, {file_error, Posix}}; everything already read follows exactly the rules of parse/2.

1> erli18n_po:parse_file(<<"catalog.po">>, #{include_fuzzy => true}).
{ok,#{header => #{...}, entries => [...]}}

See parse_file/1 (defaults) and parse/2.