Difference between revisions of "OWASP Internationalization"

Revision as of 19:32, 24 November 2009

Click here to return to OWASP Projects page.
Click here to see (& edit, if wanted) the template.

News

24th Nov 2009: Weilin Zong will translate ASVS and create the Chinese guidelines for future translations 5th May 2008: First Draft of General Translation Guidelines are published RC1 of general recommendations to start a translation of an OWASP document in a foreign language is released.
5th May 2008: Translating an OWASP document section is added Guidelines on how to do a document translation is released. 7th April 2008: The OWASP Internationalization project starts Juan Carlos Calderon starts the effort as part of the SoC 2008.

Why this project?

The main goal of OWASP is to spread the word about security (“Our mission is to make application security "visible," so that people and organizations can make informed decisions about application security risks.”) and OWASP has done great work so far. The number of native and secondary speakers in the world for Chinese, Spanish, French, Russian, Arabic and Indi languages are estimated in similar number to English speaking or even more (Some References at Ethnologue, Encarta, Wikipedia). It is a good time for OWASP to reach those that do not speak English to have full access to all the OWASP materials, not just a couple of documents.

Objectives

This project is the pioneer of an effort to define basic guidelines for the localization of OWASP site and OWASP projects (both documentation and software). Also define a way to do a continuous effort to keep information across the different languages in synchrony.
The main objective is to provide a framework for new translation efforts, those effort will have 2 main objectives:

1. Make OWASP information currently available, reach the people speaking of a specific language
2. Allow non-English speaking people to contribute to OWASP and have internationalization projects transfer that knowledge to English and other languages. So as you can imagine the replication effect will have great benefits to the OWASP community and the world of application security.

Road map

General Translation Guidelines

Usually a document translation involves several people in order to facilitate the translation it is necessary to provide general guidelines for the translation. First of all, we strongly support language neutrality, this is especially important when the language is spoken in many different countries or regions.

Translation guidelines should include the following information:

• Glossaries for the target language,
• Basic orthography rules
• Basic grammar rules
• English-Target Language dictionary.
• Enumeration and examples of special cases, for example use of dashes, quotes, etc.
• False cognates
• Remind the translation must remain loyal to the original text, do not add content to the document (at least on this stage)+
• Recommendation to avoid slang language
• Policy for using automated tools
• Rules to handle terms that cannot be translated.
• Recommend to run Spell and Grammar check
• Examples to the rules described
• Include a peer review strategy
• Supportive readings and links

+ Although the objective of the project is to enable people speaking foreign languages to learn from OWASP and enrich OWASP documentation. This process must be done in separated stages, initially it is desirable to have a loyal version of the official release.

We strongly suggest you ask for help of an experienced person to give the document a final look before it is published to OWASP site.

Organization

The first thing is to have a good communication and coordination strategy, we propose the following organization for a translation effort:

Roles

Although OWASP is an open project, minimum skills should be procured to ensure the translation has good quality and takes just the needed amount of time. Believe me, you won’t like to fix dozens of small mistakes for common computer world terms just because the translator is a totally outside the computer world with null knowledge on what is a hard disk :).

The proposed skills are:

• Translator(s)
  • Basic computer related knowledge.
  • Good English skills
  • Fluent in foreign language
  • Working knowledge in application security skills
• Editor(s)
  • Strong computer related knowledge
  • Strong English skills
  • Strong skills in foreign language, participation in translation project of other open source projects is a plus.
  • Strong knowledge in application security skills
• Translation leader. Person in charge of coordinate the translation effort. There are no special requirements, just the ability to manage a team of people and deliver on proposed time.

Translating Documents

This is the first release of the section, expect changed during the following weeks as we are requesting feedback from people involved in previous translations of OWASP documents, if you know one of these people please ask them to contact me

Setup

Translation Project leader and/or translation leader should create set of basic guidelines for translation as defined in #General Translation Guidelines section If the translation is going to be on a MS Word document is highly recommended to create a document template with web established styles for headers, so consolidating the document is easier The translation leader will distribute the work and set up tentative due dates for the sections based on the translators workload.

While Translating

It is suggested that once the distributed sections are ready, they are sent to the distribution list and the editor is notified

Before Delivering

In parallel to translation or after everyone has finished, the editor (or the person designated by the editor) will do the following actions

• Consolidate the whole document
• Do spelling and grammar check
• Ensure document "harmony". This is:
  • make sure the same terms are using across the document
  • topics sequence is natural.
  • Font type, size and style are the same for the same types of text.
• Add the official cover page translated to the foreign language (OWASP logo, title and trademark information)
• Add GNU license (all the OWASP work is done under this license so translation work should also be GNU)
• Add OWASP internationalization project and the specific translation project explanation and references to let readers know where they go in case of interest in the translation project. Add this page after cover page.
• Add translation credit for project leader, editor and translators just after the author name.
• Convert the document to PDF format for portability, but also let the editable version available to the public.

Finally If there is a translation project, you can send the document to the project leader for its publication in the translation project and in the original project page.

Translating OWASP pages

To make more clear the process of creating a translated page, consider the following assumptions. Our example foreign language code is “es” for Spanish and the page we want to translate is called “TranslationTest”. (Actually this page is there for you to use it ans tes for translation support of the portal on your specific language). So let’s start

You should first classify the page to translate as a main page (project description page, project content page) or support page (roadmap, links, quotes, etc)

For Main Pages (project pages only)

1. Add a new page called “PruebaTraduccion” (“Translation Test” in Spanish)
2. At the beginning of the page add the TranslatedPageHeader template by adding {{TranslatedPageHeader}}
3. At the end of the page add the TranslationInProgress template by adding {{TranslationInProgress}} in page code.
4. Go to “TranslationTest” page and click on “View Source” tab.
5. Copy the source code and start translating it locally. Then paste it in “PruebaTraduccion” page as you progress.
6. If there is links to pages that are not translated, let the reader know by adding a “(In English only)” note after the link.
7. Just before the end of the page, add a recognition section for the people that helped in the translation. Make sure to mention their role in the translation, their full name and Security certifications, refain to mention companies unless they are OWASP members or you have permission from OWASP Board to mention them.
8. Once you are done remove the TranslationInProgress template in “PruebaTraduccion” page.
9. Add a new sub-page for “TranslationTest” using your language code. This is, for Spanish, you should create a sub-page called “TranslationTest/es”.
10. In “TranslationTest/es” page just enter the following redirect statement #REDIRECT [[PruebaTraduccion]]

For Support Pages

For support pages, you do not need to add a third page in the foreign language (like PruebaTraduccion in previous example). Rather, you add the translated content directly to the “TranslationTest/es” page. Adding the TranslatedPageHeader is also not necessary.

Translating Links

Similar to templates, links are enclosed in special characters, in this case square braces. There are 2 types of links, external links will look like this

[http://www.mediawiki.org/wiki/Help:Templates here]

And should be translated as Links like this

[http://www.mediawiki.org/wiki/Help:Templates aqui]

Internal links, or links that point to pages in the OWASP site will look like this

[[OWASP WebGoat Project Roadmap|Roadmap]] 

And should be translated to

[[OWASP WebGoat Project Roadmap|Plan de trabajo]] 

For links without the second part (the one after the pipe character) just add it, Avoid changing the content if this is case otherwise you will break the link or link to a non existent page.

Translating Templates

Templates are an special type of pages that can be included as part of regular pages contents, you can learn more about them here, you can identify it in wiki code as text enclosed in curly braces like the following:

{{OWASP Book|1416452}}

To access wiki code of the template above you have to go to http://www.owasp.org/index.php/Template:MainLink. Templates do not support "/es" for translations as regular pages, instead we need to use special tags to support multiple languages in the same page. So edit the template code and change it from:

[[{{{1}}}| Main<br>({{{1}}})]]

To

<IfLanguage Is="en">
[[{{{1}}}| Main<br>({{{1}}})]]
</IfLanguage>
<IfLanguage Is="es">
[[{{{1}}}| Principal<br>({{{1}}})]]
</IfLanguage>

The previous code displays the text in the first IfLanguage tag to people with browsers in English and the second to people with browsers in Spanish language.

That is it. Now visitors with browsers configured in your foreign language will be automatically redirected to the page in that language.

Tracking Changes in Pages

In order to track changes of pages for a translation project to keep translated pages up to date, you have to track changes doing the following:

1. Login to OWASP Portal (register if you haven't, its free!)
2. Go to the page you want to track and click on the "watch" tab. After that you will be able to see all the change to that page at the Watchlist special page.
3. You can always go back to the Watchlist special page by clicking on Special Pages link at the left bottom of the site. and then click on the Watchlist special page.

There is a drawback, you will have to click the watch tab for every single page you want to track. This simple process will be enough to keep track of pages updates.

You can find more information on here:
http://www.mediawiki.org/wiki/Help:Tracking_changes
http://meta.wikimedia.org/wiki/Help:Contents#For_readers

Translating OWASP Software

Here you can find a series of basic guidelines document to help you make your OWASP tool project internationalizable.

The guidelines are available for:

• Java

Active Translation Projects

• Spanish