Support for ARB comments

[plaa]

Expected Behavior

Most places discussing how to organize and add comments to ARB files suggest the following format for comments:

{
    ...
    "@_HOME_SCREEN": {},
    "homeScreenTitle": "",
    ...
    "@_SETTINGS_SCREEN": {},
    "settingsScreenTitle": ""
}

Currently this produces the error "Metadata for an undefined key" in ARB-editor. This warning can be disabled, but that's less than ideal. I propose ARB-editor should accept this @_xyz comment convention and highlight the comment differently from other keys to make it more visible.

Also grouping localization strings with empty lines is useful, but ARB-editor autoformat removes all empty lines. I propose it should retain one empty line (possibly with a configuration option how many to retain). (EDIT: Problem was with Prettier extension, solution below)

Specifications

• Version: 0.0.12
• Platform: MacOS

[mosuem]

Ok so two issues here:

1. Adding comments to ARB files

The ARB format already supports arbitrary keys prefixed with @@x-, so @@x-comments could be used for global comments. We could also introduce a @@comment global comment, if there is a use case.
But what you are writing seems to be more targeted as comments for messages - which I would have probably rather written as

{
    "homeScreenTitle": "",
    "@homeScreenTitle": {
      "comment": "Some comment"
    }
}

The comment field is not allowed yet, but we do have description. Could you give an example of a comment which is not a description? I am open to allowing a comment field in there.

2. Supporting empty lines

ARB files are just JSON files with an added schema. The autoformatter should just be the JSON formatter, and VS Code at least seems to support retaining blank lines.

[plaa]

Thank you for the prompt reply!

Adding comments to ARB file

It seems that there is no documented way of adding developer-focused comments / structure to ARB files. When I Googled how to do it, I continuously got suggestions of using @_XYZ syntax, examples: 1 2 3

To avoid confusion with custom x-fields, I could use for example @@x-_XYZ or @@x-____XYZ____ notation for comments. It would be great if some form would be documented for general use.

Whatever the syntax, it would be good it ARB-editor could highlight the comments in a different color so that they would be easier to spot.

Supporting empty lines

Thank you for the pointer. I have Prettier extension installed, and even though it retained one empty line in *.json files, it removed all empty lines in *.arb files. Adding the following .prettierrc file fixed this (including to help others with the same issue). I'll edit my OP to exclude this.

{
  "overrides": [
    {
      "files": "*.arb",
      "options": {
        "parser": "json",
        "proseWrap": "preserve"
      }
    }
  ]
}

[plaa]

Maybe all keys starting with @@ could be highlighted differently? It would also be useful to distinguish between translation keys and metadata, and would highlight any @@x- form comments as well.

[mosuem]

Thanks for collecting those examples, which shows this is an issue which should be solved more generally. I would propose @@comment for a top-level comment and adding a comment field to messages, next to description and type.

One of the examples linked is rather about using comments to separate the ARB file into sections. I can't think of a good solution for that, except splitting up the arb file into several smaller files, or using @@x- messages as a hack. But that goes beyong the scope of this discussion...

[plaa]

My original use case is actually about segmenting the file, so that it's easier for developers to see what is where. I guess @@comment could be used multiple times, but that's bad practice in JSON. 🤔

[plaa]

To elaborate a bit: I think your suggested comments are a great addition. One of the things I've had pains with other localization formats is the indistinction between descriptions intended for translators and comments intended for developers.

Making the file format easier to structure and edit by developers would also be great, and positioned comments / segmenting would assist in that.

[mosuem]

Regarding the structuring, I really think it would be best to have multiple files. The ARB file format, in its current structure, is not made to be structured internally as it consists of top-level messages only.

We could discuss adding some sort of structuring as a new feature, but that would probably be a breaking change in the format, and give two different options of structuring. Both those things don't sound great.

[plaa]

Yes, I agree it would be a significant change. If the structuring is semantic, it would probably mean nesting the keys, which is a big change.

For larger scopes using several files is probably best. For small scopes desiring some structure, using a @@x-____LOGIN_SCREEN____ format is probably best and pragmatic. It's syntactically correct, doesn't break any tools, is understandable and easily visible to editors. If the IDE highlights @@ with a separate color it's automatically even more visible.

Do you think highlighting @@ annotated keys with a different color would be feasible? I think it would be useful even outside the scope of comments we're discussing, as it points out metadata separately.

[mosuem]

I personally think that JSON dictionaries (and ARB files as an extension) should not care about ordering, so it feels weird to use comments to format this. But then again, if it works, why not :)

Do you think highlighting @@ annotated keys with a different color would be feasible? I think it would be useful even outside the scope of comments we're discussing, as it points out metadata separately.

I filed #64.