WIP: Idea for handling of translations: Using properties files

[schneidermic0]

trafficstars

See #106

This PR shall show one possible approach how translations could be stored in separate .properties files (one file per language).

The filename pattern would be <object name>.<object type>.<language>.properties.

The keys of the properties file is determined from the JSON paths (and keys) of the language dependent field (tbd).

Examples:

field=Translatable text of a field
object.field=Translatable text of a field in an object
array[arrayKey].field=Translatable text of a field for item "arrayKey" in an array.

[albertmink]

Fields (aka translation relevant text) in a JSON document can be generally described by JSONPath specified https://goessner.net/articles/JsonPath/ with playground https://jsonpath.com/

For a JSON document

{
  "fixedValues": [
    {
      "fixedValue": "ABC",
      "description": "Fixed value ABC"
    },
    {
      "fixedValue": "XYZ",
      "description": "Fixed value XYZ"
    }
  ]
}

expression $.fixedValues[0].description identifies the JSON field Fixed value ABC.

Applied to ABAP file formats, this could be then

$.fixedValues[0].description=Festwert ABC
$.fixedValues[1].description=Festwert XYZ

///Edit To reference the elements of an array independently of the index (which might be changing):

$.fixedValues[?(@.fixedValue=='ABC')].description=Festwert ABC
$.fixedValues[?(@.fixedValue=='XYZ')].description=Festwert XYZ

[mbtools]

Sorry, but I really don't like these "json path property files". A key point of serializing to a file in git is that they are human readable and editable but this $.descriptions.methods[?(@.name=='METH1')].description=Sonne format is just for machine consumption. A big step backward for AFF. What's wrong with the equivalent JSON?

[albertmink]

Note: 'Equivalent' JSON is supported by SAP Translation Hub, https://help.sap.com/docs/translation-hub/sap-translation-hub/supported-file-formats?locale=en-US. Either way, it is just about the presentation of the data. The data model is the same.

[mbtools]

with plain json it would be so much easier to build an integration to the translation hub. isn't that even more a reason to go for json?

[albertmink]

Plain JSON contains less information. If you only store the translated text you end up with (without the lines starting with //). How can you associate the description to its method?

{
  "header": {
    "description": "Hello",
  },
  "descriptions": {
    "methods": [
      {
        //"name": "METHOD_ONE",
        "description": "One",
      },
      {
        //"name": "METHOD_TWO",
        "description": "Two",
      }
    ]
  }
}

Instead we specify

$.header.description=Hello
$.descriptions.methods[?(@.name=='METHOD_ONE')].description=One
$.descriptions.methods[?(@.name=='METHOD_TWO')].description=Two

[mbtools]

The object (array) keys would have to be included just like you showed. Otherwise translators would not have the context. It also allows the json to be sorted.

[albertmink]

Ok, and how do you know if field name or/and description has to be translated?

[mbtools]

a question of naming. key fields could go by "id" or begin with "_" (or just "name")

[schneidermic0]

@mbtools, I am sorry about my late response. Thank you for your feedback. It is highly appreciated. 👍

Some time ago, we had a meeting with experts of SAP's translation tools. They strongly recommended to use .properties files. Therefore, we decided, to start with this approach. See also https://github.com/SAP/abap-file-formats/issues/106#issuecomment-1814772291

Our idea is that the implementation should be based on the AFF-type and add serialisation/deserialization options with this data. Therefore, it should be possible to use other serialisations later if required.

However, as mentioned before, we would like to start with the .properties first.

[schneidermic0]

Regarding the integration of JSON in the translation hub. As far as I understand the documentation linked by @albertmink (https://help.sap.com/docs/translation-hub/sap-translation-hub/supported-file-formats?locale=en-US) as follows:

The syntax is as follows

{
    "key1": "value1",
    "key2": "value2"
}

As far as I understand, we could not use a deep structure because tools would need to understand this structure. I.e., the JSON should be structured with key-value-pairs. If my assumption is correct an JSON file would look like the this (based on Albert's example above):

{
    "$.header.description": "value1",
    "$.descriptions.methods[?(@.name=='METHOD_ONE')].description": "One",
    "$.descriptions.methods[?(@.name=='METHOD_TWO')].description": "Two"
}

From my point of view this is the same (or even worse ;)) than the .properties approach.

[schneidermic0]

Regarding the keys based on JSONPath:

I agree they are quite lengthy and technical. Additionally, they have only small variable parts in the key. E.g., key $.descriptions.methods[?(@.name=='METHOD_ONE')].description basically means the description for method METHOD_ONE. If I would write it by hand I would have defined a key like methods.METHOD_ONE (or similar).

Albert came up with the approach of the more generic JSON path so that it can be used (hopefully) generically for all ABAP file formats. And I like this idea.

However, maybe, it is an option to define pattern in the beginning of the properties file (as comment?!?) to simplify the keys and make it more readable:

# formatVersion=1
# key description=$.header.description
# key methods.$1=$.descriptions.methods[?(@.name=='$1')].description
# key attributes.$1=$.descriptions.attributes[?(@.name=='$1')].description

description=Hello

methods.METHOD_ONE=One
methods.METHOD_TWO=Two

attributes.ATTRIBUTE_ONE=Attribute One

I am not sure (yet) whether I like it, so just take it as food for thought.

[mbtools]

I don't think there needs to be a connection between the serialized JSON of the object and the translation texts. Whatever is reading the translations needs to understand where to put them.

Your last example goes in the right direction. It should not need the meta/comment part to be interpreted when deserializing.

Generically, something like "table.key1.key2.textfield". We don't want to use the DDIC names, but nicer descriptions like AFF.

More thinking...

[schneidermic0]

Thanks for your update. This means, your concern isn't using .properties or .json but using JSONPath as keys because they are too technical. Is my understanding correct?

[mbtools]

Correct. Unless it's binary data, the files should be as simple as possible. For humans to edit, or actions/other tools to process. That's why AFF json is much better than the abapGit xml formats, for example.