core:text/i18n: separate get() calls requiring a quantity parameter from calls not requiring it (proposal)

[mgavioli]

Discussed in https://github.com/odin-lang/Odin/discussions/3501

This is not about a bug, but the outcome of the discussion quoted at the top (and also on Discord), advancing a proposal.

In summary, the idea is that the message catalogues used by core:text/i18n (primarily for .mo-based catalogues, but QtLinguist-based ones would also benefit from it.) distinguish — as two different forms of entries — between translating strings which never change (regardless of the quantity of item involved, for instance: "All temporary files have been deleted") and which do not require a quantity numeric parameter and of strings which may vary according to this quantity and thus require such a parameter.

In the current API, both the quantity and the source catalogue are optional and the compiler is obviously perfectly able to distinguish between , for instance: i18n.get("Some key", number) and i18n.get("some key", catalogue)

A tool for collecting translatable strings from Odin sources — as GNU xgettext or Qt Linguist do for C/C++ sources — which needs to output two different types of entries from them, would have much more troubles distinguishing that the first is a pluraliseable string (with a numeric parameter) and the second is immutable (the second parameter is a pointer to a catalogue), as the surface syntax is parallel (a literal string and an identifier).

So, in part to ease the job of such tools (without which the current i18n API is largely unusable) and in part to reflect the nature of underlying things, the proposal is to split the current i18n API for translations in two:

• a get_n() proc group which, in the current procs get_single_section and get_by_section, renamed to get_single_section_w_plural and get_by_section_w_plural, the numeric parameter is no longer optional, but required;
• a get() proc group which, in the current procs get_single_section and get_by_section, which keep their names, the numeric parameter is absent.

In summary of summary (!):

    get_single_section :: proc(key: string, catalog: ^Translation = ACTIVE) -> (value: string) {...}
    get_by_section :: proc(section, key: string, catalog: ^Translation = ACTIVE) -> (value: string) {...}
    get :: proc{get_single_section, get_by_section}

    get_single_section_w_plural :: proc(key: string, quantity: int, catalog: ^Translation = ACTIVE) -> (value: string) {...}
    get_by_section_w_plural :: proc(section, key: string, quantity: int, catalog: ^Translation = ACTIVE) -> (value: string) {...}
    get_n :: proc{get_single_section_w_plural, get_by_section_w_plural}

I have a PR ready to be submitted implementing the proposed changes in core/text/i18n/doc.odin, core/text/i18n/i18n.odin and tests/core/text/i18n/test_core_text_i18n.odin.

Comments and/or objections are welcome!

[mgavioli]

A small application collecting translatable strings from Odin sources (with several limitations) is available here. It reflects the current API and can be easily updated, if the API changes.

[Kelimion]

Excellent, thanks.