Using linguistic resources
This page gives a brief overview to the kind of data and resources that can be useful in building a new language pair for Apertium, and how to go about building them if they do not already exist.
 What dictionaries?
Each Apertium language pair requires 3 dictionary files. For instance, for the English-Afrikaans pair, these would be:
apertium-en-af.af.dix.xml: a list of Afrikaans words and their variants;
apertium-en-af.en.dix.xml: a list of English words and their variants;
apertium-en-af.en-af.dix.xml: a list which maps the Afrikaans words in af.dix to their equivalent English words in en.dix
These dictionary files are not discussed further on this page — more information on their layout and structure is available at the HOWTO.
 Collecting linguistic data
Before these files can be produced, you need a collection of linguistic data which can be inserted into them. This data might consist of wordlists, word-corpora derived from web-crawlers such as Crubadán, grammar notes, existing translation of open-source software such as KDE or GNOME, etc. Some practical suggestions on how to build some starter wordlists can be found at Building dictionaries, but if you feel that this is too technical, just ask one of the Apertium team to put together something like this for you.
A crucial point here is that the data must either have been gathered from scratch, or must be available under a license which is compatible with Apertium's GPL. In other words, you definitely cannot just start copying published dictionaries or other material wholesale into your data store.
It is unlikely that this data will be appropriate "as is" for use in Apertium, and it will need a greater or lesser amount of revision first. You do not have to be a first-language speaker to collect and systematise the data, but you should have a reasonable knowledge of the language, and be working in consultation with first-language speakers.
It is possible to collect a small amount of linguistic data, and start testing it with Apertium. However, this is not recommended - your views of how the data should be segmented may change, leading to wasted work. Once initial contact has been made with the Apertium team, it is better to aim at collecting a sizeable wordlist (1,000-2,000 words) and coming to some preliminary decisions on how the language's sentences are structured. In the meantime, maintain contact with the Apertium team, and discuss any issues that have arisen in regard to your data collection.
You will have a good idea of how the language works from your own knowledge of it, and from reviewing published materials (eg dictionaries, grammars) about it. From this you can decide on the particular elements of information that need to be noted down for each word in order to capture its meaning and variants.
In many widely-spoken languages (e.g. English, German, Spanish) there may be a range of material available, and there may also be a significant number of people willing and able to work with you on collecting and systematising the data. However, for lesser-used languages (e.g. Breton, Kashubian) the amount of material and the number of helpers may be small — many of the lesser-used languages in KDE, for instance, only have one or two people working on them. If you are in this position, it is important to remember that "the best is the enemy of the good". You will not be able to create your language's equivalent of the Oxford English Dictionary overnight, and there is no point in trying. It is better to aim at a good basic foundation which will allow you to develop it later and fill in the gaps as time and manpower present themselves. So, for instance, while it might be ideal to have citation sentences for each word giving its typical use in context, this may be a luxury you cannot as yet afford.
For some languages, the free dictionary project, Wiktionary has reasonable data. For example, for Faroese, nouns come with declination, which can be automatically extracted by means of scripts. Some of this can be quite complicated, but if there is a site which has this information freely available in a standardised format, contact someone on the Apertium team, and they'd be glad to help you write a script, or to write the script for you.
 More sources of linguistic data
The Wiki of the Association for Computational Linguistics has a List of resources by language which often contains useful links (often clearly marked for whether the resources are Free Software or Proprietary).
 Ways of storing data
- See also: Speling format
It is easiest to start storing the words in a spreadsheet or database. Gnumeric, KSpread or OOCalc are examples of the former. Once complete, your data can be exported into a format (e.g. CSV, comma-separated values) where it can be used by other software to build the Apertium dictionaries. Databases such as PostgreSQL, MySQL and SQLite are even more attractive, provided you are familiar with them, since the data can be manipulated in various ways before exporting. Further information on the software mentioned here is [at this other page].
You will then have to decide which basic information you should store for each word. For many European languages, for instance, you might consider using the following information for nouns:
- base form, or lemma (usually the singular)
- English meaning (assuming English is the other language of the pair)
- clarification (where any enhancement of the meaning is required)
- plural form
- gender (eg masculine, feminine, neuter)
- number (eg singular, dual, plural)
- part of speech (by definition, this will be "noun")
- source (where you got the word).
Each base form should have a one-to-one relationship with its meaning in the target language. So, for instance, in Welsh, rather than have:
- pres - money, brass
we would have:
- pres - money
- pres - brass
This is to allow easier manipulation of the data (for example, with this format it is easier to turn your Welsh-English wordlist into an English-Welsh one).
The meaning in your target language should be kept as short as possible - choose the single word that matches the greatest proportion of contextual uses of the source language word. Then use the "clarification" entry to expand on this basic meaning. For instance, in Welsh, we would have:
- Cymraeg - Welsh (language)
- Cymreig - Welsh (non-language)
where the former is used to talk only about the Welsh language, and the latter is used to refer to anything else (places, customs, etc). This approach will allow nuances of meaning to be captured when appropriate, without cluttering up the equivalence.
The "part of speech" entry will allow you to combine various wordlists whenever necessary without losing information about the contents - you will be able to separate them again. Typical parts of speech in European languages might be: noun, proper noun, adjective, verb, adverb, preposition, pronoun, conjunction, interjection, interrogative, demonstrative, numeral.
For example, a spreadsheet (which closely mirrors the Speling format) might look like:
lemma ; surface form ; part of speech ; symbols beer ; beer ; noun ; sg beer ; beers ; noun ; pl red ; red ; adj ; go ; goes ; verb ; pres.p3.sg go ; go ; verb ; pres.p2.sg go ; go ; verb ; pres.p1.sg go ; went ; verb ; past
If you decide to note down idioms or longer phrases, you can give them some sort of POS tag such as "phrase", and let the grammarians argue over their exact structure later!
The "source" entry is not essential, but may be useful if anyone ever queries whether your data infringes someone else's copyright. By definition, your data store will eventually contain all the words contained in, for example, small dictionaries — although the words themselves are not copyright, the selection and arrangement of words in a dictionary is. By using a "source" entry, you will be able to demonstrate that your selection of words has been independently gathered.
Once you have your lists of words, you will have the contours of your language's landscape in place. However, to fill in the details, your data will also need to contain information on what forms these words take in context. For instance, in English the past tense of "see" is "saw". In Latvian, "sirds" (heart) is in the nominative case, but it has other forms such as "sirdij" (to a heart, dative) or "sirdis" (hearts, accusative). So, instead of noting the plural for your nouns, for instance, you may have decided to note instead some information which will allow you to predict these variants. In Latin, for instance, the accepted method is to note the nominative and genitive singular of any word, which will then allow you predict its other forms (eg "mensa, mensae" - table).
If you have not done this as yet, the next stage is to go over your linguistic data adding information of this sort (these "sets" of variants are called "paradigms" in Apertium, and are an important component in how it works). In some cases, you may need to extend your spreadsheet or database to allow new entries. For instance, for English and German verbs the standard notation is to note the third person singular forms of the present, past and perfect tenses in addition to the infinitive:
- bringen, bringt, brachte, gebracht
- bring, brings, brought, brought
so you might add additional columns for these. In the same way, additional columns could be added for noun cases, adjectival variants, and so on.
In many European languages, there is a rich set of conjugational variants for verbs. It may be possible to capture these fairly easily, as in French or Spanish, by making the verb ending (eg -er, -ar) the main determiner for the variants, and noting any consequent spelling changes:
- hablar (to speak), hablo (I speak)
- avergonzar (to shame), avergüenzo (I shame).
In other languages (eg Greek), the situation may be more complex, and not so amenable to simple categorisation. Nevertheless, it is important to try to abstract some rules for verb form generation - at the very least, this may offer the possibility of another useful language tool, a verbform generator (see, for instance, Verbiste (French), Compjugador (Spanish), Rhedadur (Welsh). Many other conjugators can be found on Verbix or by doing a simple Google search.
After this work, you should have a set of internally consistent data that captures a lot of the key information about the most common words in your language, and you are now ready to start importing that data into Apertium. That merits a separate page [ref].
 Some final notes
The first is that Apertium is a work in progress. It was originally developed for closely-related Romance languages, and is now expanding into a translation platform for a much wider range of languages. By definition, this means that future work will involve trying to accommodate linguistic constructs that are new to the system. For instance, the mutation system in Celtic languages has been handled by a small addition to the dictionary format. This is challenging and exciting, but by the same token you should not expect that the Apertium team will have an easy (or indeed any!) answer to a particular problem. Be prepared to collaborate on developing Apertium to deal with that problem.
The second is that your carefully-collected data is not just an input into Apertium. You can use it to produce an online dictionary for your language (see, for instance, Eurfa for Welsh), and it can also be converted easily into a print dictionary using something like LaTeX. The data can be used to build a spelling checker or a grammar checker using the tools available from the Gramadóir project.
Without language data, it is impossible to build language tools. So by putting together your datastore, you have already taken an enormous step towards making the riches of your language available to others.