|
Introduce new localization mechanism?
EBALLOT PROPOSAL
Introduce a new localization mechanism that meets the following requirements:
Don't define a new file type to hold localizations. Instead, define new SARIF objects that can be persisted as external property files (and therefore also inlined in the sarifLog.inlineExternalPropertyFiles property, should #321 be approved).
It should be easy to switch from one language to another (which suggests that the design should permit -- but not require -- all the localized strings for one language to be stored together).
It should be possible for a log file to include a "partial" set of localized strings, containing just those strings that are referenced elsewhere in the log file.
It should also be possible to ship "comprehensive" sets of strings, that is, strings for all rules and notifications defined by a tool component. Since rule ids are not required to be unique, and since the order (index) in which rules appear in a translation object cannot be enforced, this implies that each rule needs a unique id.
API IMPACT
In the toolComponent object:
Add a guid property of type string in GUID format.
In the reportingDescriptor object:
Add a guid property of type string in GUID format.
In the run object:
Add a translation property of type array of translation objects, which can be externalized.
Define a translation object with the following properties:
language of type string in ISO 639 format, e.g., "en-US".
toolComponentTranslations of type array of toolComponentTranslation objects.
Define a toolComponentTranslation object with the following properties:
toolComponentGuid of type string in GUID format: matches toolComponent.guid.
location of type artifactLocation: where the translation can be obtained.
semanticVersion of type string: the semantic version of the tool component for which the translation was made.
partialTranslation of type bool: true if this object contains a subset of the strings defined by the tool component.
globalMessageStrings of type object with multiformatMessageString-valued properties: its property names are a subset of the names in toolComponent.globalMessageStrings.
reportingDescriptors of type array of reportingDescriptorTranslation objects.
notificationDescriptors of type array of reportingDescriptorTranslation objects.
Define a reportingDescriptorTranslation object with the following properties:
id of type string: matches reportingDescriptor.id.
guid of type string in GUID format: matches reportingDescriptor.guid.
shortDescription of type multiformatMessageString.
fullDescription of type multiformatMessageString.
messageStrings of type object with multiformatMessageString-valued properties: its property names are a subset of the names in reportingDescriptor.messageStrings.
NOTES
SAMPLE SARIF
{
"runs": [
{
"tool": {
"driver": {
"name": "CodeScanner",
"guid": "",
"ruleDescriptors": [
{
"id": "CA2101",
"guid": "",
"defaultConfiguration": {
"level": "error"
},
"messageStrings": {
"default": {
"text": "This is bad: {0}.",
"markdown": "This is _bad_: {0}."
}
}
],
"notificationDescriptors": [
]
}
},
"results": [
{
"ruleId": "CA2101",
"rulePointer": "drive/ruleDescriptors/0",
"message": {
"messageId": "default",
"arguments": [ "42" ]
}
}
],
"translations": [
{
"language": "en-US",
"toolComponentTranslations": [
{
"toolComponentGuid": "",
"location": {
"uri": "https://example.com/tools/CodeScanner/en-US/1.3.4/translation.sarif.external-property-file"
},
"semanticVersion": "1.3.4",
"partialTranslation": true,
"fullName": "The localized full name of my application",
"shortDescription": {
"text": "A tool for finding bad things."
},
"fullDescription": {
"text": "The best tool for finding bad things. Get your copy today!"
},
"globalMessageStrings": {
"call": {
"text": "Function {0} was called.",
"markdown": "Function `{0}` was called."
}
},
"ruleDescriptors": [
{
"id": "CA2101",
"guid": "",
"shortDescription": {
"text": "This is what happens when you do a bad thing.",
"markdown": "This is what happens when you do a _bad_ thing.."
},
"messageStrings": {
"default": {
"text": "This is bad: {0}.",
"markdown": "This is _bad_: {0}."
}
}
}
],
"notificationDescriptor": [
]
}
]
}
]
}
]
}
https://github.com/oasis-tcs/sarif-spec/issues/338
|
