Closed Bug 1374605 Opened 4 years ago Closed 1 year ago

[translate] Show file-level comments


(Webtools :: Pontoon, enhancement, P3)



(Not tracked)



(Reporter: tchevalier, Assigned: abowler2, Mentored)


(Blocks 1 open bug)


(Whiteboard: outreachyround19)


(1 file)

The notes at the top of .lang files always contain critical information for the file (general context, testing URL, screenshots…) but they can’t be displayed in Pontoon.

Examples for snippets and a form:

We should find a way to somehow expose this information in Pontoon
There's some talk about a "l10n brief" comment in ftl, too. Probably also valid for other file formats.
Right now, the first contiguous comment in the file which is not attached to a message or section is parsed as the resource comment. I would like to consider adding special sigils for it, e.g. /// or //!.
I'm not initially supportive of the special sigil for that (go away, sigils!), and I believe that the location of the comment (top of the file) is enough, but either way, FTL supports it.
We only need to figure out where to display this information, other than that it's pretty straightforward.
Priority: -- → P3
Summary: Expose .lang notes → [translate] Show file-level comments
What about showing comments as collapsable sections? We can have up to 3 of them: file, section, string. Maybe the file one could be collapsed to one line be default.

As someone who spends a lot of time writing those comments, I feel like the current situation is already far from ideal, with comments losing the original line endings. Maybe collapsable sections could help with that.
Also - for FTL it seems that the section comment is included, but with no distinction between that are the string comment - it just looks like:

    section comment string comment

which usually doesn't make any sense unless you specifically design the section and string comments with this in mind.
Since Pontoon doesn't have a special UI for group (section) comments, the best thing we can do right now is to add them to string comments. They usually apply to all strings within the group.

Is this something we can revisit soon? I.e., post TN?

I'm asking because in Fluent for bedrock, we're coming back to URLs etc for files, and I'd love to advise them in a direction that's kinda solid. won't work, for example, but what would?

Group comment for now? Should I pretend we have semantic comments already and go with something like

# @url https://www-dev...


Why not simply convert .lang file-level comments to .ftl file-level comments?

Triple-hash comments (###) are also always standalone and apply to the entire file;
they are file-level comments. They can be used to provide information about the
purpose or the context of the entire file.

I'm not a big fan of giving semantic comments a special treatment in Pontoon until Fluent actually support them.

AFAICT, file-level comments are completely ditched in pontoon right now? I'm only seeing group and entry-level comments making it into the UI?

(In reply to Axel Hecht [:Pike] from comment #10)

AFAICT, file-level comments are completely ditched in pontoon right now? I'm only seeing group and entry-level comments making it into the UI?

Right, but that's what this bug is trying to change.

... which is why I started my comment 8 with "can we revisit this soon?" Can I nominate this to be triaged as a P2? Or can I get "I can click on a stage URL for a string" on the voted list we talked about on the drivers meeting?

Hello Matjaz ~ I would be happy to work on this bug. If you could just summarize what is needed that would be great ~ April

Hi abowler2, it turns out we need to figure out the details of this bug within the team. We plan to do that early next week.

We can sync over IRC/email to find something else to work on the meantime.

Here's more details on how we plan to fix this bug:

  1. Create new fields in the Entity model: group_comment and file_comment. Make sure to all include a data migration.

  2. When reading FTL source files:
    2.1. Populate both of the newly added fields.
    2.2. Do not prepend Entity.comment with group comments.

  3. In the UI, we should render (and linkify) all three comment fields as separate entries. Since File Comments can be long (and aren't so important), we should only show 1 line by default (and add ability to toggle full comment content).

  4. Read all existing FTL files across all projects to make sure existing data is handled properly. For this, we likely don't need to make any changes to the codebase (force-sync should do).

Test file:

Assignee: nobody → abowler2
Mentor: m

Hello Matjaz ~

I just want to verify that for the data migration mentioned in item #1 I will need to run makemigrations and then migration after creating the new fields.

If so, then the documentation shows those being run through in the root directory. However, it appears as though the current migrations are within ~/pontoon/base/migrations So, which file do I need to run the migration in?

If not, then can you provide me with documentation and/or direction on completing the data migration.

TIA ~ April

Sorry for the confusion - it's not a data migration, just a regular model migration.

After you save the changes to the model, you just go to docker shell using make shell and then run:

./ makemigrations base
./ migrate
Closed: 1 year ago
Resolution: --- → FIXED
Whiteboard: outreachyround19
You need to log in before you can comment on or make changes to this bug.