Fink

i18n - 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 /

Next: 3. Procedure for Updating Documents