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 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 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.