Available Languages: | Deutsch | English | Français | 中文 (简) (Simplified Chinese) |

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.

Contents

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:

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:

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:

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:

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.

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

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

  1. Open a terminal
  2. Create a directory somewhere to contain the Fink xml branch, e.g:
    mkdir -p ~/Documents/Fink-i18n
  3. Move to that directory:
    cd ~/Documents/Fink-i18n
  4. 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:

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

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

  1. Move to the directory that contains the files you checked out, e.g:
    cd ~/Documents/Fink-i18n/xml
  2. 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)

  1. Constants files: (e.g. xml/web/constants.*.inc) (see below)
  2. Static PHP files (e.g. xml/web/*.en.php)
  3. Documentation navigation files (e.g. xml/web/doc/nav.*.inc) (same handling as constants.*.inc)
  4. Document Index (xml/doc/doc.en.xml)
  5. User's Guide (xml/users-guide/uguide.en.xml)
  6. Advanced (xml/advanced/advanced.en.xml)
  7. FAQ (xml/faq.en.xml)
  8. Running X11 (xml/x11/x11.en.xml)
  9. CVS Access (xml/cvsaccess/cvs.en.xml)
  10. ReadMe (xml/fink-readme/readme.en.xml)
  11. Internationalization (xml/multilingual/multilingual.en.xml)
  12. ReadMe (xml/fink-readme/readme.en.xml)
  13. Security (xml/security/security.en.xml)
  14. Packaging Tutorial (xml/quick-start-pkg/quick-start-pkg.en.xml)
  15. Packaging (xml/packaging/packaging.en.xml)
  16. Porting (xml/porting/porting.en.xml)
  17. 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):

  1. Copy the xml file
    cp x11.en.xml x11.fr.xml
  2. 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" > ...
  3. Very important notice: Check that the cvsid line near the beginning of the file is not splitted.
  4. Save as UTF-8. Be aware that the encoding must be utf-8 and take care not to change anything but true text.
  5. 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.

2.8 When You Get Commit Access (Team Leaders)

Once you have been given commit access, you should

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:

2.10 Update our website

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

  1. Open a terminal
  2. log in web server via ssh:
    ssh username@shell.sourceforge.net
    You'll need to give your SourceForge passphrase.
  3. Move to the directory which contains our web pages:
    cd /home/groups/f/fi/fink/htdocs
  4. update the website from CVS:
    ./update.sh
    Important note: when you do this you will activate everything that's been placed in web/xml.
  5. log out from web server:
    exit
  6. 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:

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:

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:

  1. Changes to the Internationalization HOWTO (this document) will always be made on this schedule, because such changes affect all translation teams.
  2. 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.

  1. Unicode in XML and other Markup Languages
  2. Tutorial: Character sets & encodings
  3. W3C Internationalization Activity
  4. UTF-8 and Unicode FAQ for Unix/Linux

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.

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.

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:


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 $