1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
---
breadcrumbs:
- - /developers
- For Developers
- - /developers/tools-we-use-in-chromium
- Tools we use in Chromium
- - /developers/tools-we-use-in-chromium/grit
- GRIT
page_name: grit-design-overview
title: GRIT Design Overview
---
# Introduction
This document is intended as a rough overview of the design of GRIT.
Before reading this, you should probably read the [GRIT user's
guide](/developers/tools-we-use-in-chromium/grit/grit-users-guide) for
background.
# Design Overview
The source of truth in GRIT is the .grd file (an XML formatted file). This file
format is only an input format for GRIT; it is not a resource format in and of
itself. For some good examples of what .grd files look like, see the [various
such
files](https://cs.chromium.org/search/?q=file:%5C.grd&sq=package:chromium&type=cs)
in the Chromium project.
The structure and semantics of the .grd file are encoded in the various
sub-classes of grit.node.Base.
From the .grd file and various files it may reference, GRIT builds up an
in-memory representation of all of the "source" resources, most often the
resources as they are designed in English, although a different source language
than English may be specified.
Through the <outputs> section, the .grd file also specifies which
languages to output, and in which formats.
GRIT uses the idea that identical messages (translation units) should receive
identical translations, to avoid translators having to translate the same
message multiple times. To enable multiple identical messages to have different
meanings (e.g. "open" as a noun vs. "open" as a verb) GRIT adds the ability to
specify a *meaning* attribute that allows the messages to be translated
differently.
The .grd file may contain various types of resources:
* Non-translatable resources such as images, that should get output by
GRIT to whatever resource format is being used. This is what the
<include> node is for.
* Single mesages (translation units) using the <message> node.
Non-translatable parts of messages may be demarcated with <ph>
nodes (short for "placeholder").
* Structured resource formats, that GRIT can break down into multiple
messages. Examples are HTML files and things such as dialog box or
menu definitions from Windows .rc files. The <structure> node
is used to reference these formats, and always points to a file
external to the .grd file.
A *formatter* is something that knows how to take a .grd file and turn it into
the resource format (e.g. Windows .rc files, Chromium .pak files, Android
resource files, etc.) in each of the different languages specified in the
<outputs> section.
The various formatters available are in the grit.format package.
A *gatherer* is something that knows how to break a structured resource
(<structure> node) into messages, and how to create a translated version
of the structured resource file.
The various gatherers available are in the grit.gather package.
A *tool* is something you invoke from the command line. Tools live in the
grit.tool package and are invoked as grit xyz where xyz is the name of the tool,
and the binding from name to package is specified in the grit.grit_runner
module.
GRIT is meant as a tool that, given a set of input files in the source language,
and a set of translations, can produce resource files in all target languages
(by default, using pseudo-translations for messages that do not have available
translations). It has basic features for packaging messages for delivery to
translators, and for receiving translations back from translators. Its formats
for this are the .xmb format (generated by the grit xmb tool) and the .xtb
format (referenced by the <translation> node in the .grd file). These are
very basic formats that contain the messages, with placeholders and with any
descriptions provided to give the translators context. The assumption is that
there is some other system that reads the .xmb format, provides translators with
another format or a UI that lets them translate more easily, then takes what it
receives back from translators and packages it back up into the .xtb format.
|
