Decide on the section body

[zbraniecki]

We currently place all messages that belong to a section inside a section body.

Since there's no semantic meaning to sections, maybe we want to reconsider that, and flatten the structure.

I'm not sure what would be the consequences, for example for ability to pick section comments and apply them for all messages that belong to the section by l10n tools, but I'd like to discuss it.

[stasm]

This bit me when I was working on migrations, too. OTOH, it wasn't hard to work around it. In general, I'm all for flatter structures and I'd support this change.

For tools, since FTL is a list of translations, making it flat means fewer assumptions the tool has to make about the translation resource. Tools could still choose to use something similar to CSS's position: sticky to always show the current section and its comments visible to the user. Or, in a single loop replicate the section comment to all messages following it. (Moving messages between sections would require a bit more work; but is it common?)

Lastly, if we change this, I would also consider changing the name from section which implies a body of things, to header or something similar.

What do you think?

[stasm]

@mathjazz Do you have more thoughts about how this would impact tools?

[mathjazz]

I'm not exactly sure I understand the proposal. Are you thinking about flattening the ast, while keeping the section syntax unchanged?

[stasm]

Yes. Right now the structure is a nested one and can be roughly represented as:

resource [
    message { … }
    message { … }
    section [
        message { … }
        message { … }
    ]
]

This requires that any tools which work with the AST be able to recurse into sections when they iterate over all message. Fortunately sections cannot be nested inside other sections, so this recursion is only one level deep at most.

The proposed change is to flatten the structure like so:

resource [
    message { … }
    message { … }
    header { … }
    message { … }
    message { … }
]

[mathjazz]

Thanks for clarifying!

I'm ok witht the proposal. The impact on tools is minimal. It actually simplifies the code a bit.

[Pike]

I'm torn. I did fall into the trap of hierarchies when hacking on c-l, but for tools, you also want to gather the section comment. Which might be easier to get from the parent than a sibling.

Can we compare pseudo code for that? The ASTs pasted so far didn't have comments ;-)

[stasm]

Can we compare pseudo code for that? The ASTs pasted so far didn't have comments ;-)

@Pike: Do you mean the pseudo code for looking up the closest previous section comment given a message?

[Pike]

Yeah.

[stasm]

I see two scenarios and I think the second one is more common in tooling. Please correct me if I'm wrong.

1. Get the value, the comment and the section comment of a message given the identifier.
2. Iterate over all messages in a single resource and build a list of (value, comment, section comment) tuples.

The code in all cases is quite similar because a message in a section doesn't store any data about that section. We still need to iterate over all entries in a resource.

Scenario 1: get the value and the comments

Before the change:

def get_message(resource, id):
    for entry in resource:
        if entry.type == "message" and entry.id == id:
            return (entry.value, entry.comment, None)
        if entry.type == "section":
            msg = get_message(entry.body, id)
            if msg is not None:
                value, comment, _ = msg
                return (value, comment, entry.comment)

After the change:

def get_message(resource, id):
    section_comment = None
    for entry in resource:
        if entry.type == "message" and entry.id == id:
            return (entry.value, entry.comment, section_comment)
        if entry.type == "section":
            section_comment = entry.comment

Scenario 2: get all messages with comments

Before the change:

def get_messages(resource):
    for entry in resource:
        if entry.type == "message":
            yield (entry.value, entry.comment, None)
        if entry.type == "section":
            for msg in get_messages(entry.body):
                value, comment, _ = msg
                yield (value, comment, entry.comment)

After the change:

def get_messages(resource):
    section_comment = None
    for entry in resource:
        if entry.type == "message":
            yield (entry.value, entry.comment, section_comment)
        if entry.type == "section":
            section_comment = entry.comment

[Pike]

From a tooling perspective, I envision code paths to pass around entries, so you probably need to either iterate over all entries up to the current or we'll want to have the python API actually include a back-reference to the section entry (and its comment).

So yeah, not a big deal either way.