Skip to content

Latest commit

 

History

History
119 lines (87 loc) · 4.36 KB

2024-05-28-i18n-examples.md

File metadata and controls

119 lines (87 loc) · 4.36 KB

Example of possible model file structure for internationalization and localization

  • Proposed during 2024-05-28 Tech meeting with details added on 2024-05-29.
  • See example files far below for illustration.

Structure and format

  • Model files and translations sit together in the same repo and same branch.
    • Possibly the same directory as well.
  • Translations of a model file name will be in name.lang.md format.
    • lang is an ISO 639-1 two-letter language code.
    • Alternatively, we can opt for the IETF BCP 47 language tag (so it can handle cases like simplied Chinese and traditional Chinese scripts)
  • Heading = String ID
    • The tool will recognise sections from their headings (Summary, Description, etc.) and can use these to match translations of the same section.
    • For languages with missing sections, fall back to English.

Translations

  • Class names must not be translated. More notes on proposed requirements in Tech Team Meeting 2024-05-21 minutes https://github.com/spdx/meetings/blob/main/tech/2024/2024-05-21.md
  • Contents in Profile conformance, Summary, Description, and Entries sections are meant to be translated.
  • While contents in Metadata, Properties, External properties restrictions and Referenced sections are less likely meant to be translated.
    • The spec generation tool may choose to ignore the translations.
  • The translation of headings themselves will be in a separate file (for example, model-headings.csv), so for one heading there will be only one translation needed per language.
    • For every new heading/section added to the model description structure, a heading entry has to be added to this file.
  • The working process of the human editors of all languages will be pretty much unchanged. They will still work on the Markdown-like text files.
    • Each language community will work on a seperated group of files.
    • Adaptation in tooling is needed to pick up translations for generation.

Examples

In the examples below:

  • Agent.md is a main model file (in English), it can have all the headings/sections permitted in a model file.
  • Agent.ja.md is a Japanese translation corresponding to Agent.md
    • ja is a language code for Japanese.
    • The headings/sections allowed here will be more limited that in a main model file.
  • model-headings.csv contains the English headings and their translations.
    • The first line is the header line, with the same language codes as ones used in model file names. In this case, it uses the IETF language tag.

Agent.md:

SPDX-License-Identifier: Community-Spec-1.0

# Agent

## Summary

Agent represents anything with the potential to act on a system.

## Description

The Agent class represents anything that has the potential to act on a system.

## Metadata

- name: Agent
- SubclassOf: Element
- Instantiability: Concrete

Agent.ja.md:

SPDX-License-Identifier: Community-Spec-1.0

# Agent

## Summary

エージェントは、システム上で動作する可能性のあるものを表します。

## Description

Agent クラスは、システム上で動作する可能性のあるあらゆるものを表します。

Note that there is no Metadata heading, like in Agent.md, here, as the content in that section is not meant to be translated.

model-headings.csv:

_id,en,ja,sv,th,zh-Hans,zh-Hant
0,"Profile conformance",プロファイル適合,Profilöverensstämmelse,ความสอดคล้องของโปรไฟล์,符合配置文件,輪廓一致性
1,Summary,まとめ,Sammanfattning,สรุป,概括,概括
2,Description,説明,Beskrivning,คำอธิบาย,描述,描述
3,Entries,エントリー,Inlägg,รายการ,条目,參賽作品
4,Metadata,メタデータ,Metadata,เมทาดาตา,元数据,元数据 
5,Properties,プロパティ,Egenskaper,คุณสมบัติ,特性,特性
6,"External properties restrictions",外部プロパティの制限,"Restriktioner för externa egenskaper",ข้อจำกัดคุณสมบัติภายนอก,外部属性限制,外部屬性限制
7,Referenced,参照,Refererade,ถูกอ้างจาก,引用,參考

Note that zh-Hans is for simplified Chinese (used in Mainland China, Singapore, etc.) and zh-Hant is for traditional Chinese (used in Hong Kong, Macau, and Taiwan).