Fink Internationalization (i18n) Howto Guide

This document is a work in progress.

Welcome to the Fink Website Internationalization Howto. This document is intended to offer guidelines for people who want to contribute to the i18n effort for the Fink website.

1 Introduction
2 The Documentation Files
3 Procedure for Updating Documents
4 Additional Resources
5 Appendix
- 5.1 CVS codes

1 Introduction

1.1 What is going on with internationalization of the Fink website?

The Fink project has undertaken an effort to add full internationalization support to its website, in order to make the site more accessible worldwide. Thanks to Baba Yoshihiko, there is now a framework in which pages in multiple languages can be employed.

1.2 Languages

We currently have volunteers working on the following languages:

Danish
Dutch
English (the baseline documentation)
French
German
Italian
Japanese
Spanish
Simplified Chinese

1.3 Organization

A chart of the organization of the i18n team is available here.

1.4 Helping out

If you wish to help out with the internationalization effort, there are several things that you can do:

Join discussions on the fink-i18n mailing list. This is where we will discuss the mechanics of internationalization, announcements of updates to documents will be made, etc.
Look over the translation for your own language. You may have a translation that flows better than does the official one, you may find a translation error, and other possibilities.
Become a translator yourself. If your language isn't currently represented (or even if it is), and you think you can provide an effective translation, then you may want to volunteer to be a translator for your language.
Be advised, however, if you are the first person to work on your language: there are quite a few documents that you will have to translate initially. Once this is done, there typically will be small changes made.

2 The Documentation Files

The purpose of this chapter is to introduce you to the Fink documentation files, how to access them, and how to send changes to the Fink website and activate them.

2.1 Requirements

To work on the documentation files as a member of a translation team, you need:

A CVS client to allow you to download the documentation from the Fink xml tree.
A UTF-8 compatible text editor--a dedicated XML editor is a plus, since many of the files on the Fink website are generated from XML files.
A checkout of the Fink xml tree, as per the instructions below.
Working knowledge of Fink is also beneficial.

Note: "team member" is defined as someone who translates but is not ultimately responsible for uploading files to the Fink website.

Team leaders must meet the above requirements, but should also have:

A SourceForge account (free registration).
Commit access to the Fink documentation tree. To get this, send a message to the fink-18n mailing list, letting them know your SourceForge username. One of the i18n Core Team will make the arrangements for you to have CVS access to the documentation section.

Note: a "team leader" is here defined as a person who is responsible for actually uploading changed files to the Fink website and activating those changes.

2.2 Environment Settings

You will want to set up your environment to save you some typing later on. The ensuing discussion assumes that you are using the built-in command-line tools on Mac OS X or another Unix-like OS.

Team leaders only: Modify your login files to add the CVS_RSH environment variable.
1. If you are using bash or zsh add the following:
```
export CVS_RSH=ssh
```
  to your .profile.
2. If you're using tcsh add the following:
```
setenv CVS_RSH ssh
```
  to your .cshrc.
  This will tell cvs to use ssh to gain access to the files. This is required.
All members: Create a file called .cvsrc in your home directory with the following line in it:
```
cvs -z3
```
By doing this, CVS will use level 3 compression by default (it's a good thing!)

After these operations make sure to start a new terminal window to make sure your CVS_RSH environment is set.

2.3 Acquiring Files to Work on

For now, you must check out the xml branch of the web site:

Open a terminal
Create a directory somewhere to contain the Fink xml branch, e.g:
```
mkdir -p ~/Documents/Fink-i18n
```
Move to that directory:
```
cd ~/Documents/Fink-i18n
```
For non-leader team members (or leaders awaiting access): Login to fink.cvs.sourceforge.net anonymously:
1. ```
cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink login
```
2. Push the enter key (no password, anonymous as default)
3. Check out the xml module:
```
cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
Team leaders: Check out using your username:
1. You don't have to do the login step above, but can go right to
```
cvs -d:ext:yourusername@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
  where yourusername is of course your SourceForge username. You may get a message about the DSA key of the server being unknown. Go ahead and answer yes.
2. In this case you should enter your SourceForge passphrase at the prompt.

2.4 File Standards

There are two different file standards you will have to be concerned with as a translator:

Static (PHP only)
These are documents whose organization (e.g. item numbering) isn't expected to change much on a day-to-day basis. In this case the document just has a PHP file, which you will translate.
Dynamic (XML generates PHP and HTML)
These documents (e.g. the FAQ) are updated and restructured more often, so they need the facility to be reorganized dynamically. Such documents use an XML file as the basis by which PHP and HTML files are generated, via a script. As a translator, your responsibility is to translate the XML file.

In addition, you will have to translate or modify a few other files, such as Makefile, nav.xx.inc, constants.xx.inc. Without them, the pages either will not appear on the web site or will not appear correctly.

All files are utf-8 encoded, consequently you should not change the encoding unless it is wrong (i.e. not utf-8), or use any html entities but those already in the English files.

2.5 Update to latest revision

Since other translators will change some files (don't be afraid about that, CVS can take good care of it) after you checked out the files, it is a good idea that you update your working copy to the latest revision frequently. For updating, you can:

Move to the directory that contains the files you checked out, e.g:
```
cd ~/Documents/Fink-i18n/xml
```

Update it, e.g:

cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink update -dP

for team members without commit access, or

cvs update -dP

for team leaders.

You may find a letter in front of one or more of the filenames when you do this. Consult the Appendix for more information, as well as the cvs man page.

2.6 Initial Translation

The files to translate, in order of priority, are:

Title (English version file)

Constants files: (e.g. xml/web/constants.*.inc) (see below)
Static PHP files (e.g. xml/web/*.en.php)
Documentation navigation files (e.g. xml/web/doc/nav.*.inc) (same handling as constants.*.inc)
Document Index (xml/doc/doc.en.xml)
User's Guide (xml/users-guide/uguide.en.xml)
Advanced (xml/advanced/advanced.en.xml)
FAQ (xml/faq.en.xml)
Running X11 (xml/x11/x11.en.xml)
CVS Access (xml/cvsaccess/cvs.en.xml)
ReadMe (xml/fink-readme/readme.en.xml)
Internationalization (xml/multilingual/multilingual.en.xml)
ReadMe (xml/fink-readme/readme.en.xml)
Security (xml/security/security.en.xml)
Packaging Tutorial (xml/quick-start-pkg/quick-start-pkg.en.xml)
Packaging (xml/packaging/packaging.en.xml)
Porting (xml/porting/porting.en.xml)
News (xml/news/news.xml)

Be sure to check also the subdirectories in xml/web for php, constants or navigation files to translate.

Do not translate or modify any php file in xml/web and its subdirectories which contains "Generated from" near the beginning of the file. You will find the corresponding xml file to translate or modify in the xml tree.

The constants.*.inc files, as well as the nav.*.inc files, are intended to deal with hard coded items in the PHP include files. They are mostly menu items and such, located on top and left of the pages. You should separate them from the scripts and create a constants.xx.inc file for your language. To do this, just issue the following command in a terminal window:

cp constants.fr.inc constants.xx.inc

where xx is your language code (e.g.: de for German language). Next, you'll want to translate the single quoted part of the define lines into your language. In case you don't understand French, here is the translation into English:

Don't forget to change the locale, i.e. en_US to de_DE for German language.

/* The Sections.  Used in Menu Navigation Bar */
define (FINK_LC_ALL, 'en_US');

/* The Sections. Used in Menu Navigation Bar */ 
define (FINK_SECTION_HOME, 'Home'); 
define (FINK_SECTION_DOWNLOAD, 'Download');
define (FINK_SECTION_PACKAGE, 'Packages'); 
define (FINK_SECTION_HELP, 'Help'); 
define (FINK_SECTION_FAQ, 'F.A.Q.'); 
define (FINK_SECTION_DOCUMENTATION, 'Documentation'); 
define (FINK_SECTION_MAILING_LISTS, 'Mailing Lists'); 
      
/* The Home Subsections. Used in Menu Navigation Bar */ 
define (FINK_SECTION_HOME_INDEX, 'Index'); 
define (FINK_SECTION_HOME_NEWS, 'News'); 
define (FINK_SECTION_HOME_ABOUT, 'About'); 
define (FINK_SECTION_HOME_CONTRIBUTORS, 'Contributors'); 
define (FINK_SECTION_HOME_LINKS, 'Links'); 
      
/* The word 'Sections'. Used in Menu Navigation Bar */ 
define (FINK_SECTIONS, 'Sections'); 
      
/* Used in FAQ/Documentation Sections: */
/* Contents as Table of contents, Next as next page */ 
/* Q as question, A as anwer */
define (FINK_CONTENTS, 'Contents');
define (FINK_NEXT, 'Next');
define (FINK_Q, 'Q');
define (FINK_A, 'A');

/* Printer */
define (FINK_PRINTER, 'Printer');
define (FINK_PRINT_VERSION, 'Print Version');

/* Footer */
define (META_KEYWORDS, 'Mac OS X, Fink, Debian, Macintosh, Apple, UNIX, Open Source,
             download, free software, port, development, package management');
define (META_DESCRIPTION, 'The Fink project wants to bring the full world of Unix Open
             Source software to Darwin and Mac OS X. We modify Unix software so that it 
             compiles and runs on Mac OS X and make it available for download as a coherent
             distribution.');
define (HEADER_HOSTED_BY, 'Hosted by {img}');
define (FOOTER_AVAILABLE_LANGUAGES, 'Available Languages');
define (FOOTER_GENERATED_DYNAMICALLY, 'Generated dynamically from');
define (FOOTER_DATABASE_LAST_UPDATED, 'Last updated on %a, %d %B %Y,  %R %Z');
define (FOOTER_LAST_CHANGED, 'Last changed by {author} on %a, %d %B %Y,  %R %Z');

Note: the first lines of Footer section have been splitted for display purpose, do not split them in the file.

When you translate, you normally follow the steps as below (suppose you are translating the Running X11 document into French):

Copy the xml file
```
cp x11.en.xml x11.fr.xml
```

Edit the line to declare it is French and its encoding is UTF-8

<?xml version='1.0' encoding='utf-8' ?> ...
<document filename="index" lang="fr" > ...

Very important notice: Check that the cvsid line near the beginning of the file is not splitted.
Save as UTF-8. Be aware that the encoding must be utf-8 and take care not to change anything but true text.
Once you are done, or just to test it, edit the Makefile to include your language as:
```
LANGUAGES_AVAILABLE = en ja fr
```
then type make in the directory. This should generate your PHP (and possibly some other) files as well as other files matching the languages in the Makefile.

Note: If you see some misspelling or errors in the English file, don't change it, but instead report it instead to the fink-i18n list, so that the master English file is changed.

2.7 Check Your Work

Before your work gets uploaded onto the Fink website, you should check how the documents look.

The easy way: Open the HTML and PHP files in your web browser. PHP files won't look exactly like you see them on the website, however.
The best way: You can use your built in web server to view your documents as they will appear as it will on Fink's website. Assuming that you are using the built-in server:
1. Edit /etc/httpd/httpd.conf, e.g. via:
```
sudo pico /etc/httpd/httpd.conf
```
2. Look for a line that says:
```
#LoadModule php libexec/httpd/libphp4.so
```
  and remove the #
3. Look for a line that says:
```
#AddModule mod_php4.c
```
  and remove the #
4. If you are running a version of Apache older than the built-in one for Panther then you may also have to look for a line that looks like
```
AddType application/x-httpd-php .php
```
  and put a # in front of it.
5. Save the file and exit your editor.
6. Start Personal Web Sharing in System Preferences--if it's already running then turn it off and back on again.
7. The easiest way to make everything visible is to move your checkout of the xml Tree into the Sites folder in your Home folder. You can then open the homepage in your web browser at the following URL:
```
http://127.0.0.1/~USERNAME/xml/web/index.php
```
  where USERNAME should be replaced by your username.

2.8 When You Get Commit Access (Team Leaders)

Once you have been given commit access, you should

Set up an SSH key for your SourceForge account.
1. Set the key up on your machine following the instructions from SourceForge.
2. Type in the terminal:
```
cat ~/.ssh/id_dsa.pub | pbcopy
```
  This will copy the contents of the file directly to your pasteboard, to avoid spurious linebreaks. Make sure not to copy anything else to the pasteboard until you're done.
3. Log in to your account on SourceForge.
4. Select "Account Options"
5. Go to the "Host Access Information" area, and click on "Edit SSH Keys for Shell/CVS"
6. Click on the form and use Cmd-A, Cmd-V
7. Click the button.
Check out the xml tree using your username.
1. If you checked out the whole xml tree initially, then you should rename your local copy. You can use the Finder for this.
2. Move to that directory in a terminal window:
```
cd ~/Documents/Fink-i18n
```
3. Do the checkout of the xml tree:
```
cvs -d:ext:yourusername@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
  where yourusername is of course your SourceForge username. Enter your passphrase where prompted.
4. Copy the files that you were working on from your old tree to the new one. Feel free to use the Finder, making sure that they go in the same subfolder as they were initially.

2.9 Committing the Changes (Team Leaders)

Now you need to send your changes to the main server. To do this you need to make sure that you have commit access. You also should make sure that you are always using the latest version of XSLT in unstable tree, which is libxslt-1.1.4-1 from Fink as the time of writing this document.

The procedure is different according to the nature - static or dynamic - of the documents:

Static: (PHP files only) To commit these documents do the following:
1. Open a terminal.
2. Move to the directory that contains the file you want to check in, e.g:
```
cd ~/Documents/Fink-i18n/xml/web
```
  if you created your xml tree under Documents/Fink-i18n/ in your home folder, and you want to commit a PHP file from the xml/web directory.
3. If the file is a new one that you've created, then you need to add it to the list of files, e,g.:
```
cvs add download.ru.php
```
  Give your SourceForge passphrase at the prompt.
  If the file already exists, you can skip to the next step.
4. Commit the file, e.g. in the prior example:
```
cvs ci -m "message" download.ru.php
```
  where once again message should indicate what you've done. Give your SourceForge passphrase at the prompt.
  Note: you can commit multiple files at once.
Dynamic: (XML and PHP) After you've modified the XML file, do the following:
1. Open a terminal
2. Move to the directory that contains the file you've added or modified, e.g.
```
cd ~/Documents/Fink-i18n/xml/faq
```
  if you've been working on the FAQ.
3. Now run
```
make check
```
  To ensure that the file is valid.
4. If the XML file is a new one that you've created, then you need to add the XML file and its Makefile (assuming, of course, that you edited it to create the files for your language) to the list of files, e,g.:
```
cvs add faq.ru.xml Makefile
```
  You'll need to give your SourceForge passphrase.
  If the file already exists, you can skip to the next step.
5. Commit the files, e.g.:
```
cvs ci -m "message" faq.ru.xml Makefile
```
  where message is a descriptive message about what you've done. Enter your SourceForge passphrase at the prompt.
6. Now run
```
make && make install
```
7. If you get an error message telling you that a directory foo is missing under xml/scripts/installer/dmg, then move to it with:
```
cd ../scripts/installer/dmg
```
  and create the directory with:
```
mkdir -p foo
```
  Then return to the previous directory and rerun
```
make && make install
```
8. Move into your copy of the Fink xml tree, e.g:
```
cd ~/Documents/Fink-i18n/xml
```
  if you created your xml tree under Documents/Fink-i18n/ in your home folder.
9. If the XML file was new, you'll need to do some more CVS adding. For example, if you have been working on the FAQ, then, you'll want to run (e.g.):
```
cvs add web/faq/index.en.php web/faq/general.ru.php \ 
web/faq/relations.ru.php web/faq/usage-fink.ru.php \ 
web/comp-general.ru.php web/faq/comp-packages.ru.php \ 
web/faq/usage-general.ru.php web/faq/usage-packages.ru.php \ 
web/faq/upgrade-fink.ru.php web/faq/mirrors.ru.php \ 
web/faq/faq.ru.html web/faq/header.ru.inc \ 
scripts/installer/dmg/faq.ru.html
```
  For other documents, the files will of course be different--use whatever gets created for your language when you run make install.
10. Don't forget to add and commit any file you've created (be it constants.xx.inc, header.xx.inc, nav.xx.inc, etc.)
  If the file already exists, you can skip to the next step.
11. Commit the whole tree:
```
cvs ci -m "message"
```
  Where once again message is a descriptive log message (you may want to use the same one as when you committed the XML file). Enter your SourceForge passphrase at the prompt.
  The reason that you have to do two commits in this case is that it's required to ensure that the files show the correct creation time and person who last modified them.

2.10 Update our website

Want to see your efforts from our website right now? Just do the following:

Open a terminal
log in web server via ssh:
```
ssh username@shell.sourceforge.net
```
You'll need to give your SourceForge passphrase.
Move to the directory which contains our web pages:
```
cd /home/groups/f/fi/fink/htdocs
```
update the website from CVS:
```
./update.sh
```
Important note: when you do this you will activate everything that's been placed in web/xml.
log out from web server:
```
exit
```
See your efforts:
```
open /
```

3 Procedure for Updating Documents

Since the English documentation is the baseline, it must be updated first. Such an update may come from a member of the i18n team (e.g. the English Documentarians) or directly from the core developers.

In order that things go smoothly, the following procedures should be followed:

3.1 Call to Translate

If a new document is posted, or changes are made in the English documentation, a message should be posted to the fink-18n list informing all translators of the fact. The message will contain the following:

A note in the subject line indicating that this is a request for translation, e.g. "[translation]", or "[translation-delayed]" for items where the English documentation is going online with a delay.
In addition, the filename of the base file should be included somewhere in the message.
A full diff, e.g.:
```
diff -Nru3 -rlast_revision rhead 
```
to show the modifications in context.

Note: since committing the XML file automatically produces a message on fink-commits that meets all of these criteria, an easy thing to do is to forward such a message and re-title the subject. However, this will fail if many changes were made.

3.2 New Document

The English version of the document is committed and activated, and it is translated as below.

Note: When the new document is inside a new directory, you shoould add that new directory to the Makefile located in the xml directory. Otherwise the built process will not complete successfully.

3.3 New Translations

The language team leader (or someone else with CVS access) will commit and activate each document as it becomes ready.

This classification includes:

The first time a translation is made of an existing document.
Partial translations of an existing document.
Translation of a new English document

3.4 Prompt Update to Existing Documentation

The base English documentation is committed and activated immediately--whomever changed the XML should commit the HTML and PHP, and do the activation. The translation teams then update their versions, commit all of the files (XML and PHP), then activate the changes.

Never change a dynamically generated php file; change the xml file instead.

Check that the cvsid line near the beginning of an xml file is not splitted.

Notes:

Changes to the Internationalization HOWTO (this document) will always be made on this schedule, because such changes affect all translation teams.
Changes to the static documents (PHP files not generated from XML) will always be made on this schedule as well, because it's hard to delay their activation.

3.5 Delayed Update to Existing Documentation (XML-generated files only)

In this case, the English version of the XML file is committed, but not the PHP and HTML files, i.e. stop after step 5 under of Dynamic under 2.9. All translators do their work and commit only their XML file (i.e. the same as for English) within an agreed-upon timeframe. All of the PHP and HTML files will be generated, committed, and activated simultaneously at an agreed-upon time by one person, e.g. someone from the i18n core team.

3.6 For Developers and English Language Documenters

The current policy is that all documents should be updated according to the prompt update schedule, unless you have a specific reason to do otherwise.

4 Additional Resources

4.1 Important Links

Internationalization is a complicated subject. The resources provided below can serve as a valuable second source of information. You are advised to read them carefully if you wish to delve deeper into this subject.

4.2 Editors

There are various editors you can use to edit files. This is a short list of recommended editors. Some editors are complicated to use or command line only and thus not suited for everybody. We will try to provide a list of editors suitable for about anyone.

SubEthaEdit - A modern Rendezvous enabled graphical editor for Mac OS X.
BBEdit - A versatile and well known albeit none-free editor.
Morphon XML-Editor - A free, specialized XML Editor. Very good for editing XML files.
Cyclone - An free Interface for the Apple Text Encoding Converter.
LineBreak - A simple utility for Mac OS X that converts line breaks in text documents.

4.3 Useful Tools

The command line interface is not meant for everyone. The following list of useful tools are often graphical frontends to those command line tools. They are provided for your convenience.

MacCvsX 3.3 - Graphical frontend to CVS. (This is recommended for Team Leaders only!)

5 Appendix

5.1 CVS codes

When you are updating your CVS checkout, you may see some letters before the filenames. These represent the following conditions:

P: There is a new version of the file via a patch.
U: There is a new version of the file via download.
M: The version in your local repository has been modified.
C: Your version conflicts with that in the remote repository. You should resolve this by editing the file and merging your modifications.
You can use
```
rm file; cvs update file
```
where file is the offending file, to resolve the conflict, and then apply the changes from the backup of your file that exists under.#file-version, where version is the revision that your file started from.
?: The file is neither in the remote repository nor in the files to be ignored.
A: The file has been added but not committed yet.
R: The file has been removed but not committed yet.

Copyright Notice

Copyright (c) 2001 Christoph Pfisterer, Copyright (c) 2001-2020 The Fink Project. You may distribute this document in print for private purposes, provided the document and this copyright notice remain complete and unmodified. Any commercial reproduction and any online publication requires the explicit consent of the author.

Generated from $Fink: multilingual.en.xml,v 1.23 2012/11/11 15:20:15 gecko2 Exp $