Procedure

The AROS website is built from text-only files, stored in an online Git repository. These are later put into a template, creating the AROS site you can see on the web.

To summarize, it is highly recommended that you:

• make your intentions known to the developer ML and see if your services are needed (to be on the safe side)
• read this whole page
• read the Working with Git page
• apply for Git access
• sign up for both the developer and website Mailing List (ML)

Git

If you are not familiar with Git, read up about it on the Working with Git page as stated. In short: Git works kind of like FTP in that it focusses only on files. However, instead of moving single files around like FTP does, you now keep a full (and synchronized) copy of the sources on your hard disk. You then work offline on these files, and when wished, synchronize your local changes with the main repository on the server. The named source files you will be working with are plain text-files (no HTML). The fancy looks of the AROS website, together with the menus, are added in a separate process on the server which transforms these text files into a full HTML website. This will be covered later to some extend.

It is highly recommended to wait until you get Git access before you start. It makes it easier to send in and change your translated files later. Be warned that it may take a little while to get Git access - sometimes even several weeks after your initial request. It can be a challenge for patience, should you be really enthusiastic... luckily for you, you can make a head-start by downloading a copy of the website sources from the AROS website. This is simply a copy of the website Git repository just mentioned. Besides, it also makes a great way to get familiar with the way content is handled and the archive is structured. Only drawback to this route is that later you will have to manually copy your files to your 'real' Git clone. (There is a scenario possible where you translate from the archive and send the files to the ML, but the extra work this brings with it is not recommended.)

When you have Git access, perform a clone of the website sources with Git. This will download the current repository to your HD, containing all the files of the website. The locations is:

https://github.com/aros-development-team/documentation.git

When browsing the local copy (or the downloaded one) you will notice the many different language extensions behind files. Each extension corresponds to a specific language, and as you can guess the same will be needed for your translations. Now simply pick an existing page (English preferred), duplicate this file in the same location while adding the correct extension, e.g. contribute.en (English) -> contribute.nl (Dutch). You can then translate the contents of the page.

Character encoding

The character encoding of your to-be-translated files require extra attention. The difference of languages and the symbols they use requires that text-files use a specific encoding capable of showing the correct symbols. Should you translate for a generic western language (e.g. English, German) you have little to worry - just make sure to configure your text-editor to save files with ISO-8859-1 or ISO Latin-1 encoding. When your language uses more 'exotic' symbols to western standards (e.g. Russian or Greek), you will require different settings. Especially when configuring a new website translation it is recommended to contact the Dev ML list for advice. Also consult the documenting page for further information.

Committing

When done, commit your files to the repository for processing. Please use typical log messages, like "German translations" or "updated German X page" and try to bundle more than 1 file into a commit (when related). Key changes can better be committed separately: should an error be made, the change can be easily undone by the administrators without throwing away your other work for that particular commit (take care, since the system synchronizes all copies, you can even loose your work locally!).

How are the plain text files on the server turned into the website? It's a script, that takes the source texts and converts them into HTML/PHP pages suitable for browsing. This process is called 'building', and can also be done on your machine for testing purposes - more on that later. The website performs builds once every few hours (or days), after which your pages will be up for browsing on the website.

Exception to the rule is when a whole new language section is added: there are more tweaks required for this in the configuration of the build process. Depending on your expertise, you can better contact the Dev ML for instructions.

Checking your work

Checking your texts is advised on two points: spelling and mark-up errors.

Spellchecks should be considered obligatory, optionally re-reading your work can help. These combined should catch 99% of spelling and grammar errors, and involve little work. Correct language use does add to the representativeness of the site.

Mark-up errors are another story. These are mistakes made in tags used in the source document. Tags are special symbols/codes, like links or lines like '===' that indicate another line is a header. When present, these mistakes break the 'building' process for that page. Despite these errors, the page will still be generated and put online -but- with nasty error messages and the broken parts. The building process does report all errors automatically to the website Mailing List (ML). Extra information is also displayed, making fixing the problem easier. (You should therefore always be signed up to the website ML.) You can also wait for one of the other developers to correct the error, but it generates extra work for others, and you don't learn from your mistakes. It's quite common to make errors in your first work, later most errors will just be the occasional casual mistake.

Building the website locally

You will agree that this process of just committing to the server and waiting is in a way 'flying blind'. How can you (reasonably) prevent faulty pages ending up on the website in the first place? By building the website yourself too, just like it's done on the server. It requires installing some extra software (Python), but afterwards you can check your work with the same script that creates the website HTML files on the server; it's no magic. You work more efficient this way, keep the site tidy and save other developers some time. For a how-to on building locally and the required tools, please check the documenting page.

As with fixes, the new pages should show up in a few hours (at most a day) on the website.

Localization character sets

AROS uses the default AmigaOS charactersets for encoding languages. Below is a list of the ones used. Please try to ensure you do not use characters that are not included in those encodings.

• ISO-8859-1

  • catalog descriptors (.cd) in english
  • albanian.ct catalan.ct danish.ct dutch.ct faroese.ct finnish.ct french.ct german.ct irish.ct icelandic.ct italian.ct norwegian.ct portuguese.ct spanish.ct swedish.ct

• ISO-8859-2

  bosnian.ct croatian.ct czech.ct hungarian.ct rumanian.ct slovak.ct slovene.ct

• ISO-8859-3

  maltese.ct turkish.ct

• ISO-8859-4

  estonian.ct latvian.ct lithuanian.ct

• ISO-8859-5

  bulgarian.ct macedonian.ct serbian.ct ukrainian.ct

• AmigaPL

  polish.ct

• Amiga-1251

  russian.ct

Procedure

AROS, like AmigaOS, offers the option of storing an application's text-strings in a separate file, allowing easy and efficient localization. The catalog files for AROS are located mostly within the main code repository, which is different from the website repository. In this case you can either perform a complete Git clone, or browse the Git repository trough your browser and download specific files.

The OS repository can be accessed by browser using this link https://github.com/aros-development-team/AROS allowing you get one or two files efficiently. A complete Git clone needs to be performed by:

git clone https://github.com/aros-development-team/AROS.git

Note the Git clone is quite large (200MB) and thus takes some time to complete. Don't get intimidated by the size of the repository: you only need to focus on a fraction of these files, fortunately. Now the work can begin. If ever confused, don't hesitate to ask for help on AROS-exec or the ML.

Language definitions and fonts

First, you should check for your country in Locale/Countries and language definition file in Locale/Languages. Most languages are added already. If you can't find anything like <your_language>.c there, then you'll have to create it. Try to avoid the special characters in the name of the file, this can help prevent problems with some non-utf programs (remember, AROS is meant to be portable). You can look for the most complete lang.c file and copy it to your_lang.c. Then, open the file in your text editor and translate all the text strings you need. This includes usual units, like days, months, currency etc. You can find tables with descriptions of chars in these files (collation tables); you can skip them for the first time. After compiling, your locale must appear in list of locales of Locale Pref.

What's next? If your language uses non-ISO fonts, you'll need them. Search on the Internet for open-sourced AmigaOS bitmap or True Type Fonts, which can be included to the system. Put them to the /Fonts or /Fonts/Truetype and fix the mmakefile (be careful with mmakefiles!)

Creating CT files

Now comes the actual translating work. Localizing in AROS is similar to localizing the AmigaOS. This means you can find some *.cd and *.ct files along with the code (usually in Catalog drawer). <name>.cd files contain catalog definitions and shouldn't be touched unless you have changed the program itself. The CT files contain all the translated strings, and are the object of your work. Browse the Git Tree for these files and translate them: find the most recent <name>.ct file (look for version and date in header), copy to <your_lang>.ct (much easier to translate than from <lang>.cd file) and edit it. Try to put the words in correct times, which will require you to check where they are used. It's important to keep placeholders, like %s, %d, etc., or the application will crash later.

To aid you with this copy and rename work, there is the CLI/Terminal application Flexcat. It can generate *.ct files automatically from *.cd files for your language. It's useful in the sense that it also keeps the original text as comments (for checking) and creates empty lines for your translations. It also offers compiling options needed for testing catalogs, which will be covered later. The source code of Flexcat can be found in the Git repository in AROS/tools but needs to be compiled for either AmigaOS or Linux. You can also check Aminet or ask the Developer ML.

Using Flexcat

Before generating CT files, put Flexcat in the search path of your OS. (e.g. on AROS/AmigaOS in the "C:" drawer). Now browse to the location with Shell/Terminal and issue Flexcat to create a CT file from the original CD file using the following command:

FlexCat <application>.cd NEWCTFILE=deutsch.ct

This will get you a ready-for translation deutsch.ct file. Often the version information is not taken over; copy this manually from the original file. Translate its contents and when done, commit the file to the repository.

A special notion about updating older catalog files - this can also be done efficiently with Flexcat using the following command:

FlexCat <application>.cd deutsch.ct NEWCTFILE=deutsch.ct

This will keep all the old strings and insert new additions where found. The Flexcat documentation has additional information.

Checking your work

Again, perform spellchecks and re-read texts as mentioned. Testing is possible by several methods: (1) submit them to the Git server and wait for the next nightly build. Or (2), more immediate, you can compile the locales yourself using Flexcat, then copy them to the AROS locale drawer and check with the involved application. Compiling the catalog files with Flexcat is done with the following statement:

FlexCat <application>.cd <yourlanguage>.ct CATALOG <File>.catalog

Look in locale:languages for the name of your language. The catalog filename is usually the name of your application. Choose the same name as existing catalogs for the application. Besides verifying correct text-use it is also recommended to test translations on smaller screen sizes to see if the text is still legible.