Main Help → Using the GEDitCOM Editor → Multiple Languages
A browser style can support multiple languages by writing templates that support multiple languages and providing strings for those templates in each language. The first step is to add the language to the browser style:
- Choose the "Languages→New Language..." menu command.
- In the sheet, enter the new language's name (such as "French"). The name should have no spaces.
A new set of strings will be created in the Properties section. Open the new strings and enter the ones needed for the new language. Because you usually need to translate strings already used for other languages in your browser style, the new language strings will be preloaded with your browser style's current English strings. Because it is useful to have translations for all GEDCOM tags, whenever a new browser style is created, the English language strings will be preloaded with all GEDCOM tags as keys and with a various other common genealogy terms. See other topics on this page for help in working with the new language strings.
When writing a browser style that supports multiple languages, you should never hard code text into templates or any properties that will appear in GEDitCOM II settings. Instead, you should always refer to text using "keys." The keys refer to strings in the language properties. Whenever GEDitCOM II needs the text for a key, it will look it up in the strings for the current language selected by the user. This section explains how to use keys in various parts of a browser style.
Whenever you need text in a record editing template, a tag editing template, or a subroutine, you should fetch the text using a local(key) or string(key) function allowed in expressions. For example
cell static,local("Children")
text local("Son")
cell static,local(@tag)&":"
The local(key) function will look for the "key" in the currently selected language strings. If the key is found, the string corresponding to that key is returned. If the key is not found, the key itself is returned. A common practice is to use the English version of the desired text as the key. By this method, the appropriate English string will be used if one for the current language is not available.
The third example uses an expression (@tag) as the argument to the local() function. In this case, the expression is evaluated and the result is used as the key to fetch the string. The above useful example will look for a string matching a GEDCOM tag word. This method can therefore map GEDCOM tag words to English or other language descriptions of the current type of data. For this reason, when a new language is created, it is preloaded with keys for all the GEDCOM tags; the first step in adding a new language is to translate these terms.
An alternative to local(key) is string(key). Its function is identical except that if the key is not found in the current language, the returned result is an empty string rather than in the input key string.
Sometimes it is useful to build a complex string by combining keyed strings. For example, if language key HUSB is defined as "Husband" and key NAME is defined as "Name" for English strings, the following expression would create the string "Husband's Name":
local("HUSB")&"'s "&local("NAME")
But, this approach relies on language-specific syntax. A French version would prefer "Nom d'époux," but the above expression would result in "époux's Nom." There are two solutions to this problem. The first is to avoid such compound expressions unless they can be written to work for multiple languages. The second is to write special cases when needed. To help in this second option, each language is preloaded with a <LANG> key; templates can test this key and vary the output depending on the language. The above string could handle French and English using:
if local("<LANG>")="French"
#line=local("NAME")&" d'"&lowercase(local("HUSB"))
else
#line=local("HUSB")&"'s "&local("NAME")
endif
It is best to avoid using too many such conditions, but it will inevitably be necessary for some components of a browser style. One way to avoid such issues it to rely more on images than on text.
When a browser style defines colors, fonts, or editing properties, those properties are named and are displayed to the user in GEDitCOM II in the settings window. The name that gets displayed is found by using the key for the color, font, or property to look up the text name in the current language strings. The browser style, therefore, should:
- Enter a key for each color, font, and editing property using the key column. The usual practice is for the key to be the English name for the color, font, or editing property.
- Enter that key into each language's strings with a translation of the name for that language.
When a user attaches events to individual or family records, the allowed events are determined by the INDIEvents or FAMEvents properties. These possible events appear to the user in GEDitCOM II in a dialog. The names for the events are found by using the value for the event as a key in the language strings. The browser style, therefore, should:
- For each event in INDIEvents or FAMEvents, enter the key for the name in the value column (note that the key column for events is the GEDCOM tag word; the value column is used as the key to find the name to be displayed). The usual practice is for the key to be the English name for the event. If the each language has names for all GEDCOM tags, the value may alternatively be the GEDCOM tag word.
- Enter each key into each language's strings with a translation of the name of the event for that language. If you used the GEDCOM tag for the key, that key may already be in each language's strings.
When writing templates and naming properties, it is easy to forget to add a key to each language every time you need one. As a result, many keys may be missing. The "Synchronize Strings" menu command solves this problem. Choose this command to search through all templates, colors, fonts, editing properties, INDIEvents, and FAMEvents. In templates, it will look for all uses of local(key) and string(key) and extract the keys. In properties, it will retrieve the key for each name. Once all keys are found, all languages will be checked. If the language already has the key, nothing will be changed. If the language lacks the key, it will be added with its initial value set equal to the key.
Some comments on this command are:
local() commands will be expressions
such as local(@tag) or local(@rec). These kinds of keys will be ignored because
they are not actually keys. Instead they evaluate to text that becomes the key. These keys, however,
might indicate a place in your browser style that needs extra work for proper translation.
If any such keys are found, they can be output in a report (see below).
local("Adopted by: "&#spse).
Such keys are normally not useful, but their addition will alert you to verify the possible keys corresponding to
this expression are present.local(@tag&" details")
loads a string defined by the key with a GEDCOM tag plus the word "details"
(e.g., key "BIRT details"). Because most sets of strings will have translations for GEDCOM tag words,
any key corresponding to a GEDCOM tag work will be assumed to be needed and therefore will not be included in the report
of unused keys.When synchronization is done, you will be give an option to save a report of the process. If you save a report, it will summaries the issues described above.
When doing extensive editing of language strings, it can be easier to work outside GEDitCOM Editor in text editing or spreadsheet software. To support this option, you can export and import all language strings to text files.
To export all language strings
- Choose the "Languages→Export Languages..." menu command
- Select a file name and click OK
The exported file will be tab-delimited text file. The first column will have all the keys. Each language will have its strings in its own column. All languages in the current browser style will be exported. The first row will label the columns with the first one being "Key" and the rest being the language name.
You can open the exported file with any editing software. You can delete rows with keys you do not need or add rows with new keys. If you add rows, you have to be sure the new keys are unique among all keys (hint: sort the rows by the key to quickly see duplicates next to each other; the exported file will never have duplicates). To help in external-spread sheet editing, you can add a column labeled "Context" instead of a language name. This column can have any text such as an explanation of where the key in used in the format. It is ignored when importing back into a browser style (see below).
The recommended tool for working outside GEDitCOM Editor is to create a sheet in Google Docs. These sheets can be shared by those collaborating on translations. Most importantly, sheet commands can automatically translate many terms. For example to automatically translate a phrase into many languages, do the follow:
- Set the key in column A to the phrase. For example a row to translate "Enter free-format notes" would have that text in column A.
- Create a column for English and link that row to column A. If this example is in row 256, the English cell would have "=A256"
- For each additional language column, enter '=GOOGLETRANSLATE(A256,"en","ln")' where "ln" is standard two-letter code for desired language (e.g., "fr" for French, "es" for Spanish, "sv" for Swedish, "pt" for Portuguses, ...).
This above approach only works for keys that correspond to the English being translated. It is also important to translate things like GEDCOM tags. Here the key would be a GEDCOM tag (such as "SOUR") and translations are English and all other languages would need translation of "Source" and not "SOUR". These lines have to be translated manually. Alternatively, you could use above translation option based on the English column instead of on the key in column A.
Once the editing is done, you can import the strings back into the browser style (or into a different browser style):
- If using Google Docs, download a "Tab Separated Values" file. Once downloaded, change the extension from ".tsv" to ".txt".
- Choose the "Languages→Import Languages..." menu command
- Select a file from the firt step and click OK
- Before the strings are imported, you must select from three types of imports:
- Replace all current keys and strings with imported keys and strings - for each language matching a column in the imported file, the previous keys and strings will be deleted and replaced by the imported keys and strings.
- Keep current strings but overwrite matching keys with imported strings - for each language matching a column in the imported file, keep the previous keys and strings. If the imported file has a matching key, replace the previous string with the imported string.
- Keep current strings and import only strings for new keys - for each language matching a column in the imported file, keep the previous keys and strings. If the imported file has a matching key, keep the previous string thus ignoring the imported string.
- Select one of the three options and click Import
The import process can import any number of languages where language name is in the first row and each language is a column in spread sheet. Any column named "Context" will be ignored.
To have documentation in each language, add documentation files for each language. The first step is to add a new documentation file with name matching the language. For example, to add French documentation, add a French.html documentation file. Once the file is added, you can proceed writing the documentation.
If you do not add documentation for a language, the English documentation will be used instead.