Restricting message references

[stasm]

I wrote a draft of this a few weeks ago but I didn't have the time to fully flesh it out. I decided to open an issue about it to gauge if this idea resonates with more people.

Background

I recognize and acknowledge the usefulness and pragmatism of message references. The do pose some challenges, however:

• They can be abused if used too much. They introduce indirection, and can be used to create layers of abstraction. They increase the complexity of the localization layer in general.
• They separate the translation from its surrounding context.
• They make it easier to make translation mistakes on the boundary of the reference.
• They introduce dependencies between messages and ultimately, between message sets (e.g. files). This means that a single message is no longer self-sufficient nor independent. A larger set of messages is required to format the message or even to work with it in tools.

Proposal

For mitigate the above risks, I'd like to propose a set of restrictions which will make message references safer to use, but hopefully still useful.

Messages vs. Referenceables

I'd like to make a distinction between (a) messages which can be retrieved by the application code and (b) messages which can be referenced from other messages. For the lack of a better word, I'll call the second type of messages referenceables.

1. Messages can reference referenceables, but cannot reference other messages.
2. Referenceables can reference other referenceables, but cannot reference messages.

Two levels of definitions

Referenceables can be defined in:

1. a registry, either first-party (e.g. brand names) or possibly third-party (e.g. common first names),
2. inside messages.

Crucially, translators can only create new referenceables inside existing messages. Thanks to this, every message is completely resolvable as long as the registry is available. It can be edited, moved and deleted in isolation without having any knowledge of other messages and without impacting them either.

Data Model

Message {
    referenceables: {
        "added-photo": Referenceable {
            selector: [$photoCount],
            variants: {
                [one]: "added a new photo",
                [other]: "added {$photoCount} new photos"
            }
        },
        "their-album": Referenceable {
            selector: [$userGender],
            variants: {
                [masculine]: "his album",
                [feminine]: "her album",
                [other]: "their album"
            }
        },
    },
    selector: [],
    variants: {
        [default]: "{$userName} {added-photo} to {their-album}."
    },
}

Referenceables are a concept in the data model. CAT UIs and the syntax (which is a kind of UI, come to think about it) can choose to represent them as either a flat list of consecutive units:

shared-photos.added-photo = {$photoCount ->
    [one] added a new photo
   *[other] added {$photoCount} new photos
}
shared-photos.their-album = {$userGender ->
    [male] his album
    [female] her album
   *[other] their album
}
shared-photos = {$userName} {shared-photos.added-photo} to {shared-photos.their-album}.

Or even as a Fluent-like nested construct like the one below:

shared-photos =
    {$userName} {$photoCount ->
        [one] added a new photo
       *[other] added {$photoCount} new photos
    } to {$userGender ->
        [male] his album
        [female] her album
       *[other] their album
    }.

[eemeli]

I'm not sure that this approach would necessarily provide a solution to the challenges that are presented in the "background" section.

Specifically, an issue arises from the definition of the registry. If I were to take the entire corpus of messages available in the current scope, and declare those to be the first-party registry of referenceables, the system as a whole becomes exactly analogous to a system where references to other messages are directly allowed. In other words, I at least find referenceables and messages to be far too similar for conversion from one to the other to be difficult; this to me suggests that in the data model, they ought to be the same thing.

As an alternative, I would suggest that with a data model that defines each message as belonging to an identifiable set of messages, a "resource", it becomes easy to define a linter rule that would limit all message references to only use messages in a subset of those resources that the user or organisation considers as their first-party registry.