Product SiteDocumentation Site

Fedora Contributor Documentation

Translation Quick Start Guide

Quick start guide to providing translations on the Fedora Project

Edition 0.8

Fedora Localization Project

Fedora Documentation Project https://fedoraproject.org/wiki/Category:Docs_Project

Manuel Ospina

Edited by

Paul W. Frields

Edited by

Noriko Mizumoto

Edited by

Dmitris Glezos

Edited by

Diego Búrigo Zacarão

Edited by

Piotr Drąg

Legal Notice

Copyright © 2010 Red Hat, Inc. and others.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
For guidelines on the permitted uses of the Fedora trademarks, refer to https://fedoraproject.org/wiki/Legal:Trademark_guidelines.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
All other trademarks are the property of their respective owners.
Abstract
This guide is a fast, simple, step-by-step set of instructions for translating Fedora Project software and documents.
Introduction
1. We Need Feedback!
1. Accounts and Subscriptions
1.1. Subscribing to the Mailing List
1.2. Making a SSH Key
1.3. Making a GPG Key
1.4. Applying for an Account
1.5. Signing the CLA
1.6. Introducing Yourself
1.7. Joining the cvsl10n Group
1.8. Create a Bugzilla account
1.9. Congratulations
2. Translating Software
2.1. Prepare the Directory for Download
2.2. Obtaining and Translating Projects
2.3. Committing Projects
2.4. Adding New po File
2.5. Proofreading Translations
3. Translating Documentation
3.1. Understanding the Multiple Files Structure
3.2. Creating docbook-locales File
3.3. What to Translate
4. Translating Websites
4.1. Adding New po Files
4.2. Proofreading
5. Translating Wiki Pages
5.1. Find the English Version of the Page
5.1.1. Handling Translations Without an English Version
5.2. Add the Language Template to the English Page
5.3. Create the Language Template
5.4. Add Your Language to the Template
5.5. Start the New Page
5.6. Moving Pages From the Old Translation Setup

Introduction

This guide is a fast, simple, step-by-step set of instructions for translating Fedora Project software and documents.
More information can be found in FAQ, https://fedoraproject.org/wiki/L10N_FAQ.

1. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product Fedora Documentation.
When submitting a bug report, be sure to mention the manual's identifier: translation-quick-start-guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Chapter 1. Accounts and Subscriptions

1.1. Subscribing to the Mailing List
1.2. Making a SSH Key
1.3. Making a GPG Key
1.4. Applying for an Account
1.5. Signing the CLA
1.6. Introducing Yourself
1.7. Joining the cvsl10n Group
1.8. Create a Bugzilla account
1.9. Congratulations
To become a Fedora Translator, you must sign up for accounts and subscriptions as described in this chapter. If you have questions, post them on the trans mailing list, or ask for help via Internet Relay Chat, or IRC, at irc.freenode.org on channel #fedora-l10n.

1.1. Subscribing to the Mailing List

  1. Visit https://admin.fedoraproject.org/mailman/listinfo/trans and subscribe to the main translation mailing list.
  2. Wait for the confirmation email which contains a link to confirm your subscription. Click the link to confirm your subscription.
  3. Check https://fedoraproject.org/wiki/L10N/Teams to see if there is a special mailing list for your language. If so, subscribe to that list too.

1.2. Making a SSH Key

If you already have an existing SSH key, you can use it for Fedora work. In that case, proceed to Step 2 in the following procedure. If you do not have a SSH key yet, start with the first step below:
  1. Enter the following command: 
    ssh-keygen -t rsa
    Accept the default location (~/.ssh/id_rsa) and enter a passphrase.

    Remember Your Passphrase

    You must have your passphrase to commit translations. It cannot be recovered if you forget it.
  2. Change permissions to your key and .ssh directory: 
    chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
  3. This public key (~/.ssh/id_rsa.pub) will be used for your Fedora account creation described in Section 1.4, “Applying for an Account”.

1.3. Making a GPG Key

  1. Generate a key by typing in a command line: 
    gpg --gen-key
    A series of prompts guides you through the process. The default values suffice in almost all cases. Remember to choose a good password.

    Choosing a Good Password

    A good password:
    • consists of uppercase and lowercase letters, numbers, punctuation, and other characters
    • does not include any words or names, with or without substitutions
    • is not the same as any other password used for other systems
  2. In the resulting text, find your key ID in the statement that resembles pub 1024D/1B2AFA1C. Your key ID is the 8 character word after the slash (/). In the previous example, the GPG Key ID is 1B2AFA1C. Write down your key ID.
  3. Export your public key to a public server so that others can find it with the following command, substituting your key ID: 
    gpg --keyserver subkeys.pgp.net --send-keys GPGKEYID
  4. This GPG key ID will be used for your Fedora account creation described in Section 1.4, “Applying for an Account”.

1.4. Applying for an Account

  1. To sign up for a Fedora account, first visit https://admin.fedoraproject.org/accounts and select New Account.
  2. Fill in Username, Full Name and Email, and click Sign up!. Your password will be emailed to you.
  3. Go back to https://admin.fedoraproject.org/accounts and log in with your password. The welcome page will be displayed, and it reminds you that CLA is not completed and that an SSH key is not submitted.
  4. To submit public SSH key and GPG key ID, click My Account or go to https://admin.fedoraproject.org/accounts/user/edit.
  5. In the Edit Account (user_name) page, enter your GPG key ID in GPG Key ID: field. For the public SSH key, click Browse... button located next to Public SSH Key: field and specify your public SSH key.
  6. Telephone Number and Postal Address fields are also required to fill in for signing the CLA. These information is NOT accessible by others except admin groups. Please refer to Fedora Privacy Policy at https://fedoraproject.org/wiki/Legal:PrivacyPolicy.
  7. Other fields will be displayed by any other member by visiting the user's view page.
  8. Now click Save! located at the bottom of this page to save your information.

1.5. Signing the CLA

You must complete the Contributors License Agreement, or CLA.
  1. Visit https://admin.fedoraproject.org/accounts and login your account using your user name and password obtained from the previous process.
  2. In the Welcome page, click complete the CLA or go to https://admin.fedoraproject.org/accounts/user/edit.
  3. If the information of telephone number and postal address have not been provided yet, the Edit Account (user_name) page will be appeared. Otherwise Fedora Contributor License Agreement page will be displayed. Read through the agreement carefully and click I agree if you are happy to do so.
  4. The user-view page is appeared and shows the CLA: field as CLA Done.

1.6. Introducing Yourself

  1. Create a personal page at https://fedoraproject.org/wiki/User:Username. This is very useful for Fedora contributors to get to know and contact each other.
  2. Post a short self introduction to the trans mailing list and to the list of your local team with instructions from https://fedoraproject.org/wiki/L10N_Self_introduction. Please remember to include your FAS user name and your language. With this information, sponsor can identify you for cvsl10n group joining approval.

1.7. Joining the cvsl10n Group

  1. In the user-view page, click Join a Group located in the left side bar. If you like to do this step sometime later, your user-view page can be reached at https://admin.fedoraproject.org/accounts/user/view/user_name.
  2. Click C of the alphabet, it returns the list of the groups starting with 'c'.
  3. Find the group name cvsl10n in the list and click Apply.
  4. All sponsors and administrators are notified of your application. Introduce yourself by following Section 1.6, “Introducing Yourself”. Then your language sponsor offers to sponsor you. This may take between an hour and a few days. The membership notification will be emailed to you once sponsored.

Warning

The rest of the steps help you test your access and grant you privileges to all the Fedora infrastructure you might need in the near future. Language maintainers and people starting new languages should follow them. Although they are optional for translations, everyone is encouraged to follow them.

1.8. Create a Bugzilla account

Visit https://bugzilla.redhat.com/bugzilla/createaccount.cgi to create a Bugzilla account.

1.9. Congratulations

Sit back and enjoy your achievement. You are now a fully recognized member of the Fedora community, capable of digitally signing documents and emails, submitting contributions, publishing content on the wiki, submitting bugs, following the discussions of our groups and joining other Fedora teams.

Chapter 2. Translating Software

2.1. Prepare the Directory for Download
2.2. Obtaining and Translating Projects
2.3. Committing Projects
2.4. Adding New po File
2.5. Proofreading Translations
The translatable part of a software package is available in one or more po files. These files may be maintained in any of a number of version control systems (VCSs) depending on the project, such as CVS, Subversion, Mercurial, and git. They may be hosted on either fedorahosted.org or other systems.
This chapter explains how to translate the projects hosted on fedorahosted.org. Translators work on interface to obtaining and committing po files. Before you start, you must first prepare the directories which hold your po files.

2.1. Prepare the Directory for Download

To find which projects are translatable, visit the project list at https://translate.fedoraproject.org/projects/.
Before you download any files, prepare the directory to hold files. The described structure below is an example only, and your structure can be formed differently. 
mkdir -p ~/myproject/

2.2. Obtaining and Translating Projects

Now that you have prepared a directory structure, you can download a file to translate. You may need to communicate with other translators in your language team to avoid conflict. If you are not sure, please contact your language coordinator. Also locking a file will avoid conflict.
  1. Visit your language page such as https://translate.fedoraproject.org/languages/l/ja/, and select a target release. The interface will redirect you to a page for that release, such as https://translate.fedoraproject.org/languages/l/ja/collection/c/fedora/r/fedora-13/.
  2. Scroll down the page to find the table of all projects available for that release. Use the down-arrow icon labeled Download po/ja.po in the option area of each project to download the po file as the name of your choice to the directory you created in the previous section (e.g. abrt.po).
  3. Now the file is ready for translation. Translate the po file into your language with a po editor of your choice such as Lokalize or gtranslator.
  4. Check the integrity of your file before commit. 
    msgfmt -cvo /dev/null abrt.po

Important

If any error message appears, correct it before commit.

2.3. Committing Projects

Once you finish translation work, commit the file using the same interface.
  1. Go back to your language page such as https://translate.fedoraproject.org/languages/l/ja/, and select a target release. The interface will redirect you to a page for that release, such as https://translate.fedoraproject.org/languages/l/ja/collection/c/fedora/r/fedora-13/.

  2. Login

    At the top of the page, select Sign in to visit the Sign in page, if not logged in yet. Authenticate with your Fedora Account System user name and password.

  3. Submit

    Use the up-arrow icon labeled Send a translation for po/ja.po in the option area of each project, and click the browse button to locate your translated file.
    Click the Send button to commit your translated file.
    Interface displays the message File submitted successfully. If you receive an error or some other message, please post it to the Fedora Localization Project mailing list so it can be addressed.

2.4. Adding New po File

Go to your language page such as https://translate.fedoraproject.org/languages/l/ja/, and select a target release. The interface will redirect you to a page for that release, such as https://translate.fedoraproject.org/languages/l/ja/collection/c/fedora/r/fedora-13/.
The Fedora's Transifex screen for Vietnamese language is used as an example. The page lists all projects of particular release software packages and documentation along with stats and options.
Scroll down to the bottom, the section called Untranslated Components can be found if any of particular project(s) has been untranslated and no po file created ever for this language.
The Fedora's Transifex screen for Vietnamese language is used as an example. The screenshot displays the part of Untranslated Components.
  1. To add new po, click the component to add in Untranslated Components section. It brings up the page of that project's component.
    ABRT project master page, showing Translation Files section where pot file is available.
  2. Under Translation Files section, there is the source file. Using down-arrow icon to download the pot file. Change the pot file to po file for your language translation. 
    mv ~/myproject/abrt.pot abrt.po
lokalize abrt.po
msgfmt -cvo /dev/null abrt.po
  3. Once you finish the translation, click on the Add a new translation button at that project's component page, expanding Add a translation file pane.
    ABRT project master page, showing Add a translation file pane.
  4. Click Browse button of Local file: * to locate your translated po file. In the field of or enter it here:, type your new file name comforming with the structure instructed (e.g. po/vi.po). Enter the approriate message, and then click Send button to submit.

2.5. Proofreading Translations

Note

Since Fedora 12, the composed live image has been available to download for reviewing and correcting software translation in user interface. This live image is composed around a week before Fedora Software Translation Deadline and made available by deadline date. This image should include all latest translation submitted at this point.
To proofread your translation as part of the software, follow these steps:
  1. Change directory to the package you want to proofread. For example, 
    cd ~/myproject/system-config-printer/
  2. Convert the po file to a mo file using msgfmt with -o option: 
    msgfmt -o system-config-printer.mo ja.po
  3. As a root user, overwrite the existing mo file in /usr/share/locale/lang/LC_MESSAGES/.
    First, back up the existing file: 
    su -
    cp /usr/share/locale/ja/LC_MESSAGES/system-config-printer.mo system-config-printer.mo-backup
    Now move the file converted for proofreading. 
    mv system-config-printer.mo /usr/share/locale/ja/LC_MESSAGES/
    Exit root user. 
    exit
  4. Proofread the package with the translated strings as part of the application: 
    LANG=ja_JP.UTF-8 system-config-printer
The application related to the translated package runs with the translated strings.

Chapter 3. Translating Documentation

3.1. Understanding the Multiple Files Structure
3.2. Creating docbook-locales File
3.3. What to Translate
Current Fedora Documentation material is now maintained in the Fedora Hosted system as git repositories. This includes the latest versions of the common documentation build tools. You do not need to install git to translate these materials. Instead, use Transifex, as described in previous sections, to translate these documentation materials.

3.1. Understanding the Multiple Files Structure

Unlike software, a guide has multiple po files structure. Each file corresponds to each chapter in that guide. The file name usually consists of the chapter name. This structure is very useful as more than one translator can work on certain guide same time.
Like software, go to your language page and select a target release.
The Fedora's Transifex screen for Japanese language is used as an example. The page lists all projects of particular release software packages and documentation along with stats and options.
Any entry begins with Docs indicates documentation. To access multiple files structure, click the file icon in Option.
The Fedora's Transifex screen for Japanese language is used as an example. The page lists multiple files for Japanse release-notes along with stats and options.
Use the down-arrow icon to download the target po file and use the up-arrow icon to submit. Alternatively using the pencil icon allows you to edit the file online. Please notice that the up-arrow icon for submission and the pencil icon for online edit appears only if the user is logged in.

3.2. Creating docbook-locales File

If you are creating the first-ever translation for a locale, you must first translate docbook-locales file used in all documents for your locale. The docbook-locales files are located in the Fedora Hosted repository. Visit Transifex at https://translate.fedoraproject.org/projects/p/docbook-locales/c/master/, and add your new po file by following the instruction described above.
Next, the request of locale addition needs to be made. File a bug in Bugzilla against Product Fedora Documentation with Component docs-requests and Summary [ja]: New language support request.
You may leave the details blank, or name the guide name(s) which you like to translate.

Attach Files if Necessary

If you have any problems submitting po files using above instructions, you can attach it to the bug.

3.3. What to Translate

The most important documentation for each release of Fedora are the following:
  • Docs :: docbook-locales
  • Docs :: Release Notes
  • Docs :: About Fedora
  • Docs :: Readme
  • Docs :: Readme Burning ISOs
  • Docs :: Readme Live Image

Chapter 4. Translating Websites

4.1. Adding New po Files
4.2. Proofreading
Fedora Websites are also translatable via Transifex. You can find all projects related to Fedora websites in the Fedora Websites collection, https://translate.fedoraproject.org/collections/c/fedora/r/websites/.
Download, translate, and commit website projects the same way as for software projects — refer to Chapter 2, Translating Software.

4.1. Adding New po Files

Add new po files the same as for software projects. If you are creating the first-ever translation for a locale, you must notify the Fedora Websites team to add the new language to the website. Post the request to the trans mailing list, so that the Websites team can add the language to the Apache configuration for the site.

4.2. Proofreading

Generally the Websites team provides test sites that you can use to proofread your work.

Chapter 5. Translating Wiki Pages

5.1. Find the English Version of the Page
5.1.1. Handling Translations Without an English Version
5.2. Add the Language Template to the English Page
5.3. Create the Language Template
5.4. Add Your Language to the Template
5.5. Start the New Page
5.6. Moving Pages From the Old Translation Setup
The Fedora Wiki is the repository for project-related information. Some of these pages may need to be translated in order to better serve the Fedora community. This chapter will explain, step-by-step, the proper method of translating a wiki page.

5.1. Find the English Version of the Page

English is the base language for the Fedora Project wiki, so there needs to be an English version of the page you are working on. (If there isn't an English version of the page you are working on, see Section 5.1.1, “Handling Translations Without an English Version” below.)
If there is already a language template at the top of that page, click edit link on the right side of the language box and move to step 4; otherwise, continue to step 2.

5.1.1. Handling Translations Without an English Version

If the page you create doesn't have an English version, create a new page for the English version, add the {{template|autolang}} template as noted above, and then add the {{template|needs english}} template. This will flag the page for needing an English translation as well as create a base page.

5.2. Add the Language Template to the English Page

Edit the English page, and at the top of it, add the {{template|autolang}} template: 
{{autolang|base=yes}}
The base=yes part is required for the English page. Save the page.

5.3. Create the Language Template

The {{template|autolang}} autolang template should provide a link for you to set up the language box. Click it, and an edit page will come up. Don't change any of the content and save the page. Then click the edit link on the right side of the language box.

5.4. Add Your Language to the Template

At this point you should have an edit box open with template syntax that looks similar to this: 
{{lang|en|page=''Base page name''}}
The text between lang and page= is the list of language codes. Add the language code that you are translating to this list. Use this list to determine the proper MediaWiki language code.

Please Keep the List Alphabetical

Keep the list of language codes alphabetical by code. This means German (de) should come before English (en), for example.

5.5. Start the New Page

Click on the red link for your language to start the new page. Insert the template {{autolang}} at the top of your page, so that the list of languages is there. Be certain to not include base=yes in the template for non-English subpages.

5.6. Moving Pages From the Old Translation Setup

For translated pages that aren't in the proper place, follow steps 1-4 above. Then, copy the title of the new page (e.g. Fedora Project Wiki/de). Click the move link at the top of the old page and paste the new page name in the to new title field. Edit the new page and add {{autolang}} to the top.