Skip to content

Commit a71e25c

Browse files
naveedkhan8067naveedkhan8067
authored
Schema Localization Support (#731)
* inventory support for localizations * package generation support * localization validation and docs * integrate with pipelines * empty line * sync with docs * cleanup * cleanup
1 parent 81adb4e commit a71e25c

51 files changed

Lines changed: 2890 additions & 1309 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎SchemaInventory.json‎

Lines changed: 1062 additions & 531 deletions
Large diffs are not rendered by default.

‎docs/schema-localization.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Schema Localization
2+
3+
Schema localization provide translated labels and descriptions for the respective schemas and their items.
4+
5+
## File Naming Convention
6+
7+
Localization files follow a specific pattern.
8+
9+
- For WIP schemas:
10+
```
11+
{SchemaName}.{locale}.json
12+
```
13+
14+
- For release schemas:
15+
```
16+
{SchemaName}.{version}.{locale}.json
17+
```
18+
19+
- **`{SchemaName}`** — exact schema name, case-sensitive (e.g., `BuildingPhysical`)
20+
- **`{version}`** — exact schema version (e.g., `01.00.00`)
21+
- **`{locale}`** — a BCP 47 language tag. Use a base language tag (`de`, `fr`, `es`) for broad coverage, or a region-specific tag (`es-CO`, `de-AT`) for regional overrides
22+
23+
**Examples:**
24+
25+
- For a WIP, `BuildingPhysical` ecschema:
26+
27+
```
28+
BuildingPhysical.es.json
29+
BuildingPhysical.es-CO.json
30+
BuildingPhysical.de.json
31+
```
32+
33+
- For a release, `BuildingPhysical` ecschema version `01.00.00`:
34+
35+
```
36+
BuildingPhysical.01.00.00.es.json
37+
BuildingPhysical.01.00.00.es-CO.json
38+
BuildingPhysical.01.00.00.de.json
39+
```
40+
41+
## File Structure
42+
43+
Localization files are JSON documents with the following top-level fields:
44+
45+
| Field | Required | Description |
46+
|---|---|---|
47+
| `$schema` | **Yes** | Schema identifier for the localization format. |
48+
| `name` | **Yes** | The schema name. Must match the schema actual name. |
49+
| `version` | **Yes** | Schema version string (e.g., `"01.00.00"`). Only the major version is validated. |
50+
| `locale` | **Yes** | The locale this file targets (e.g., `"de"`, `"es-CO"`). Must match the locale in the filename. |
51+
| `label` | No | Localized display label for the schema itself. |
52+
| `description` | No | Localized description for the schema itself. |
53+
| `items` | No | Map of schema item names to their localized text (see [Items](#items)). |
54+
55+
### Items
56+
57+
The `items` object can contain any `item` of a schema like classes, enumerations, etc. Each item must be represented with the exact item name (case-sensitive) from the actual schema
58+
59+
| Field | Required | Description |
60+
|---|---|---|
61+
| `label` | No | Localized display label for the item. |
62+
| `description` | No | Localized description for the item. |
63+
| `members` | No | Map of member names to their localized text (see [Members](#members)). |
64+
65+
For example, if `Building` item is present in our localization:
66+
67+
```json
68+
"items": {
69+
"Building": {
70+
"label": "Gebäude",
71+
"description": "Eine physische Gebäudestruktur."
72+
}
73+
```
74+
75+
it means that it is representing the `Building` item from the actual schema.
76+
77+
### Members
78+
79+
The `members` object inside an item represents its `properties` or `enumerators` which must also follow the exact match naming:
80+
81+
| Field | Required | Description |
82+
|---|---|---|
83+
| `label` | No | Localized display label for the member. |
84+
| `description` | No | Localized description for the member. |
85+
86+
For example, **Height** is the property of **Building** class item:
87+
88+
```json
89+
"items": {
90+
"Building": {
91+
"label": "Gebäude",
92+
"description": "Eine physische Gebäudestruktur.",
93+
"members": {
94+
"Height": {
95+
"label": "Höhe",
96+
"description": "Die Höhe des Gebäudes in Metern."
97+
}
98+
}
99+
}
100+
}
101+
```
102+
103+
## Content Guidelines
104+
105+
- **Only translate `label` and `description`.** Do not translate item names or member names — these are identifiers used in code and must remain as defined in the schema.
106+
- **`label` and `description` are independently optional.** Provide only the fields that have meaningful translations. Missing fields fall back to the original schema value.
107+
- **`label` should be a short, display-ready string** suitable for use in a UI (e.g., a dropdown option, a column header, or a tooltip title).
108+
- **`description` should be a complete sentence** describing the element, ending with a period.
109+
110+
## Version Validation
111+
112+
We make sure that the localization file is compatible with the version of the schema being used. Only the **major version** is compared. In short, localization file will be discarded if the major version of localization json do not match to the read version of the actual schema.
113+
114+
## Example
115+
116+
The following example localizes a `BuildingPhysical` schema into German (`de`) in the file `BuildingPhysical.de.json`:
117+
118+
```json
119+
{
120+
"$schema": "ecschema-localization-v1",
121+
"name": "BuildingPhysical",
122+
"version": "01.00.00",
123+
"locale": "de",
124+
"label": "Physisches Gebäudeschema",
125+
"description": "Schema für physische Gebäudeelemente.",
126+
"items": {
127+
"Building": {
128+
"label": "Gebäude",
129+
"description": "Eine physische Gebäudestruktur.",
130+
"members": {
131+
"Height": {
132+
"label": "Höhe",
133+
"description": "Die Höhe des Gebäudes in Metern."
134+
},
135+
"Name": {
136+
"label": "Name"
137+
}
138+
}
139+
},
140+
"BuildingType": {
141+
"label": "Gebäudetyp",
142+
"description": "Arten von Gebäuden.",
143+
"members": {
144+
"Residential": {
145+
"label": "Wohngebäude",
146+
"description": "Ein Wohngebäude."
147+
},
148+
"Commercial": {
149+
"label": "Gewerbegebäude",
150+
"description": "Ein Gewerbegebäude."
151+
}
152+
}
153+
}
154+
}
155+
}
156+
```
157+
158+
And a region-specific override for Colombian Spanish (`es-CO`) in the file `BuildingPhysical.es-CO.json`:
159+
160+
```json
161+
{
162+
"$schema": "ecschema-localization-v1",
163+
"name": "BuildingPhysical",
164+
"version": "01.00.00",
165+
"locale": "es-CO",
166+
"label": "Esquema de Construcciones",
167+
"items": {
168+
"Building": {
169+
"label": "Construcción",
170+
"description": "Una estructura física de construcción."
171+
}
172+
}
173+
}
174+
```
175+
176+
## Directory Structure
177+
178+
The wip and release versions of localizations files must be in respective `Locales` directory which must be created (if not already exists) on the same level where the actual schema is present. For example:
179+
180+
```shell
181+
\Domains\4-Application\{DomainGroupName}\{Domain1}\Locales\{SchemaName}.{locale}.json
182+
\Domains\4-Application\{DomainGroupName}\{Domain1}\Released\Locales\{SchemaName}.{version}.{locale}.json
183+
```
184+
185+
After creating the localization files and placing them accoding to the described structure update the inventory.
186+
187+
## Localization Validation
188+
189+
To validate the localization file locally for any potential issues, run following command:
190+
191+
```shell
192+
npm run validateLocalizations
193+
```
194+
195+
For details on how our localization API works, see [documentation](https://github.com/iTwin/itwinjs-core/blob/master/docs/learning/metadata/SchemaLocalization.md)

0 commit comments

Comments
 (0)