SUMO Living Localization Guide

Revision Information
  • Revision id: 106884
  • Created:
  • Creator: vesper
  • Comment: New article for l10n to share best practices
  • Reviewed: No
  • Ready for localization: No
Revision Source
Revision Content

READ ME FIRST

This document is being constantly created and improved by the localizer community of SUMO. The English version is considered the “core” version, but if there are any localized versions, they are considered the “improved” version, with the focus on the locale they are in.

If you want to edit the document, go for it.

If you want to discuss its contents, use the Discussion tab for this article.

Table of Contents

Some basic SUMO vocabulary

Before you start digging deeper into SUMO, here are a few useful terms that may sound confusing or new to you. If you see that something is missing on this list, let us know in the localization forum.

  • l10n - short for “localization”; comes from the 10 letters between “l” and “n” in the full word; the process of localization is the process of turning the source content’s locale into the target content locale. SUMO localization means turning English (en-US) content into a localizer’s preferred (usually native) locale.
  • locale - the language and regional elements specific to a given group of people or nation that are presented in the context of a digital setting (software, world wide web, etc.); SUMO has quite a few locales.
  • localizer - a person who performs localization; SUMO localizers are sometimes affectionately called “l10ns” (because we like to roar!).
  • (SUMO) Knowledge Base - also known as the KB; all of SUMO content presented on article pages. This is an example article page. So is the page you are reading right now, actually.
  • (SUMO) user interface - also known as the UI; the SUMO interface are the links, buttons, and other elements (e.g. the Get Involved page) that are not stored in the Knowledge Base.

SUMO UI is localized through Verbatim and Pontoon.

  • (SUMO) Contributor - a person with a SUMO account that helps users of Mozilla products through the SUMO website; in broader terms, any Mozillian that has done something to aid Mozilla’s mission.
  • SUMO Locale Leader - a Reviewer who additionally has the power and responsibility to coordinate the localizers of a given locale.
  • Revision - a version of a Knowledge Base article in a locale; revisions can be Current (= shown to the users), Approved (= older versions of current page, no longer shown to the users and stored in our database), or Unreviewed (= waiting for a Reviewer to review it). Revisions can be created and submitted for review by any SUMO contributor. Revisions are separate for each locale (= each locale has its own revision history and status).
  • Review - the process of analysing a revision for linguistic and factual correctness. Good revisions are Approved (= made available to everyone visiting SUMO). Revisions that need more work are Deferred (= sent back to the localizer with instructions on what needs to be changed).

Why becoming an Editor is a good idea

You probably know the answer yourself - feel free to add it below, in your own words!

I think that becoming an Editor of SUMO is a good idea, because…


How to become an Editor

  1. Create a SUMO contributor account here.
  2. Announce in our forums that you are interested in localizing SUMO into your locale.
  3. Wait patiently for someone from the community to contact you and guide you in your first localization task

How to start localizing if you are the only person in your language

If you are the first person in your locale, you should contact Michał from the SUMO team and he will set you up and help you get started.

Working with others

How to work in tandem (2 people in a locale)

If there are two localizers in a locale, it is a good idea to work together. If you live nearby, meeting in person can help you discuss working together in a much faster and nicer way.

When there are two localizers for the same locale, you should try to review each other’s work regularly and agree on a localization cycle that works for both of you.

You can also start working on a Style Guide for your locale, which is going to be a great document for all the future localizers that are going to work in your language. [#w_style-guides Read more about Style Guides here].

An example tandem localization cycle for two localizers (Alice and Bob) could look like this:

  • Alice localizes an article, Bob reviews it
  • Bob localizes an article, Alice reviews it
  • Once (a week/every two weeks/a month), Alice and Bob meet (online/offline) to talk about localizing SUMO and update/create the Style Guide for their locale ([#w_style-guides more details on the Style Guide are here])

How to organize a group larger than 2 people

If your locale has more than one or two people working on it (that’s great!), you can easily organize your work by pairing people, or making small teams of 2-4 people work together on localizing and reviewing each other’s work.

Try to have people of various levels of localization experience and skill in the same small group - this way, everyone learns from everyone else.

Make sure you organize a monthly meetup, offline or online - the localizers who work together, should know each other in person, as this creates a better, happier, and more connected community. If you want to organize a meetup of your localizers and need support with this, contact Michał from the SUMO team.

How to communicate with your locale group

Communication is the most important aspect of working in a group. You should decide what is the best way for all localizers in your group to communicate. Some options to consider are:

  • The main locale thread on the SUMO forums; you can find the whole list here.
  • Private messages on SUMO - useful for 1:1 communication, but not encouraged for group communication and sprint planning
  • A mailing list - some regional communities have existing lists that you can join; you can also start your own mailing list
  • Anything else that works for you all - it can be Discourse, Usenet, etc.
For real-time communication, IRC is recommended - try out this browser client

How to communicate with the global SUMO community

The global SUMO community is usually available and active in at least two places:

The SUMO localizers have their own subforum, which you can find and access here. Use it! You can also find the SUMO localizers on their own IRC channel: #sumo-l10ns.

How to communicate with the global Mozilla l10n community

Localization is present all over Mozilla, for many different aspects of the global project. If you want to learn more about localization at Mozilla, please visit http://l10n.mozilla.org/.

If you want to contact a global locale team, you can find the complete list of all locale teams at Mozilla here.

General tips for localizing SUMO efficiently

How to localize SUMO content fast and efficiently

Here are a few simple tips that can make your life as a SUMO localizer much easier, and make SUMO useful and helpful to millions of people around the world:

  1. “Real life” is always more important than helping out with SUMO. Your family, work, school - they should always be more important than a KB article.
  2. If you have more time and more energy to do more - do more! The community is always grateful for your help.
  3. Try to localize one article or update the localization of an article at least once every two days. This way, each week you can localize or update at least 3 articles.
  4. (Reviewers and Locale Leaders) Try to review at least one submitted revision a day.
  5. If you have a bigger group, [#w_how-to-organize-a-sumo-localization-event-sprint-in-your-city-or-region organize an online or offline l10n event] - you should have an event like that once every six months, if possible. You can also organize smaller, ad-hoc meetups more often, if the community wants that. Be creative and use your imagination!
  6. [#w_style-guides Use the style guide for your locale, if it’s available. If it’s not available, create one].
  7. Take breaks. You are not a machine. A rested mind is much more powerful than a tired one.

How to get to 20% of all articles localized and keep it at that level

20% may seem like a lot, when you look at the dashboard of your locale. Do not worry - it is entirely achievable, even if you are doing all of the localization on your own or with just two or three people in total.

The most important part is the “balance of effort”. When you are trying to localize 20% of all articles, you (and your localization group) should spend 80% of time localizing and 20% of time reviewing and updating. This way, you will be able to get better at both aspects of localizing the SUMO KB (translating and reviewing) - and the workload will be focused on getting new content localized.

Do not worry too much about brand new articles appearing in the KB - if they are very important and need to be prioritized, you will receive a notification in your locale thread (the full list of locale threads is here).

How to get to 50% of all articles localized and keep it at that level

50% is a great achievement - you are “half-way-there” in making all of the Knowledge Base useful to the speakers of your language!

At this stage of localization, it would be good to [#w_style-guides have a well-developed Style Guide] and work with the language rules agreed on by everyone localizing into your language.

The “balance of effort” is probably going to change a bit as well, shifting towards a 50/50 arrangement - 50% of the time you will be localizing, and the other 50% reviewing and keeping previously localized content up-to-date.

You should also try to organize an event to reach the 50%. [#w_how-to-organize-a-sumo-localization-event-sprint-in-your-city-or-region You can read about such events here].

How to get to 100% of all articles localized and keep it at that level

First of all - this is not impossible at all! The most important part is continuous work on the KB in your locale and regular check-ins with all the localizers. A bi-weekly meeting (offline or online) can definitely help with coordination.

Reaching 100% completion is a great “excuse” to [#w_how-to-organize-a-sumo-localization-event-sprint-in-your-city-or-region organize an event, and you should definitely have at least one for that reason].

You will notice that once you reach 100%, keeping it at that level is actually not that hard. How does that magic work? It’s “simply” because…

  • you created an operational, dynamic community of localizers
  • you defined a Style Guide and processes that work best for your group
  • you communicate regularly and understand how other localizers work
  • you made good friends along the way - and working with someone you like makes any type of work much easier - and much more fun!
  • reviewing and updating a fully localized Knowledge Base for your language is much easier than “starting from zero”

From this stage onward, you should still organize regular meetups, and at least one sprint every 3 months, unless the Knowledge Base does not require another sprint to reach 100% in that short period of time.

The more, the merrier - how to grow your group

How to find other people to localize with

The best place to start your search for more localizers is the SUMO contributor forum. We also have individual threads available for each locale present at SUMO, where new contributors should appear and introduce themselves.

Local events (Mozilla-related, but not only) are also a great opportunity to find people who could be interested in localizing SUMO with you.

If you know about universities with linguistic courses or language schools in your region or city, you can try and contact people organizing them and suggest SUMO as a great way to practice and learn more about online localization.

Finally, there are many communities online in many countries, dedicated to working on open source and improving the open web. If you know about them, share this knowledge with your fellow localizer in your locale’s thread.

How to organize a SUMO localization event (sprint) in your city or region

If you want to organize an event in your city or region, you are in great company! Mozillians around the world keep organizing events all the time, both big and small ones. You can see some of these events here.

What is more, Mozilla includes a dedicated community of on-the-ground supporters and organizers, known as Mozilla Reps. They know what is going on and where, and are local experts. The local Rep(s) should be your best friend(s) in organizing a successful event. Localization events at Mozilla are traditionally called...

L10n sprints

Localization sprints are occasional meetings organized by the l10n community, with the goal of reaching one or more of the milestones for their locale. They have nothing to do with running, usually. They have a lot to do with having a great time with fellow Mozillians while doing something great for the community that speaks your language.

The basic things the community has to figure out are: when, where, who, and how:

  • When will the sprint happen (a working weekday, a weekend, one day or two)
  • Where will it take place (offline or online, one or many locations for geographically spread locales)
  • Who will take part (also, who will coordinate the sprint)
  • How should the sprint look (will it be a meeting and working session only, will there be anything else happening)

An example spreadsheet for planning the basics can be found here. For more information, or if you want to organize a sprint for your locale, Michał from the SUMO team.

Here’s a list of some past l10n sprints organized by the SUMO community:

  • your sprint goes here

Leading by example - Reviewers and Leaders

How to become a Reviewer

To become a Reviewer, talk to your locale’s Locale Leaders and Reviewers. They will discuss your application and decide whether you are ready to be a Reviewer. If there are no Reviewers in your locale, you may be designated to be one, based on your past contributions to SUMO.

Becoming a Reviewer is a major step forward from 'only' localizing the KB. You agree to take on a few new responsibilities, but it also brings new opportunities to contribute and cooperate with others on a bigger scale. You will be able to shape the future of SUMO's KB in your language.

If you started your locale at SUMO 'from zero' and were the first contributor, you have technically been a Reviewer from the very first day - making sure your work is ready to be published for users speaking your language to find and use.

If you joined an existing localization group, you may consider becoming a Reviewer if you want to expand your skills and learn how to collaborate on and be responsible for content on a new level.

What does it mean to be a Reviewer

As a Reviewer, you are encouraged to keep localizing and contributing new revisions to the KB. This way, you will learn from your own work and the work of others. As a Reviewer, you will be able to:

  • Greet new members of the SUMO community who want to localize into your language
  • Work together with Locale Leaders and other Reviewers on guiding all Editors in their work:
    • through 1:1 mentoring on language and quality
    • through documentation (e.g. a Style Guide)
    • through deciding about editors in your locale becoming reviewers
  • Help organize and attend Mozilla events in your area
  • Provide fair reviews of contributions provided by all editors in your locale - and provide constructive feedback on their quality - this includes:
    • Approving good revisions and encouraging editors to continue their great work
    • Rejecting revisions that can be improved, and letting their authors know what and why could be better

The Reviewer Checklist

For maximum fun and minimum hassle, Reviewers should:

  1. Review at least 2 articles awaiting review per week.
  2. Subscribe to the updates in the locale thread for your locale.

Reviewers are also invited to:

  1. Subscribe to the locale leader mailing list.
  2. Once a month, review and update the localizer team information for your locale - use this template.
  3. Localize and maintain the central l10n documentation in your locale, starting with this collection of pages.
  4. Subscribe to the updates in the general l10n forum.
  5. Join the #sumo channel on irc.mozilla.org.
  6. Join the #sumo-l10ns channel on irc.mozilla.org.
  7. Create a style guide for your locale.
  8. Help organize two Mozilla l10n events in the region per year.

How to become a Locale Leader

There are two paths to become a Locale Leader:

  1. You joined SUMO and your language was not initially available - In this case you will automatically become the Locale Leader, because there are no Locale Leaders present. Congratulations! Don’t worry, it’s not hard to lead a locale - take a look at the Locale Leader Checklist below to make sure you know what to do!
  2. You joined SUMO and your language was available - To become a Locale Leader, you should have some experience in localizing and reviewing, first. Please contact Michał from the SUMO team. You should also talk to your locale’s existing Locale Leaders and Reviewers. Together, they will all discuss your application and decide whether you are ready to be a Locale Leader.

What does it mean to be a Locale Leader

Each Locale Leader is doing a great service to the whole online community of people using Mozilla software around the world, speaking the same language. This also brings a bit of responsibility, so please do not apply to become a Locale Leader if you cannot meet at least the majority of the requirements in the Locale Leader Checklist below.

The Locale Leader Checklist

For maximum fun and minimum hassle, Locale Leaders should:

  1. Subscribe to the locale leader mailing list
  2. Subscribe to the updates in the locale thread for your locale
  3. Once a month, review and update the localizer team information for your locale - use this template
  4. Localize and maintain the central l10n documentation in your locale, starting with this collection of pages
  5. Create a style guide for your locale
  6. Review at least 2 articles awaiting review per week
  7. Update the SUMO l10n milestone sheet for your locale when necessary

Locale Leaders are also invited to:

  1. Subscribe to the updates in the general l10n forum
  2. Join the #sumo channel on irc.mozilla.org
  3. Join the #sumo-l10ns channel on irc.mozilla.org
  4. Subscribe to the global l10n mailing list
  5. Help organize two Mozilla l10n events in the region per year
  • your link goes here

Style Guides

What is a style guide?

A style guide is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization, or field. A style guide establishes and enforces to improve communication. To do that, it ensures and enforces best practice in usage and in language composition, visual composition, orthography, and typography. (wikipedia) (example/template)

A SUMO style guide is a document that gathers all linguistic standards for a SUMO locale, created and accepted by the Locale Leaders and Reviewers. It is a set of guidelines and tips for all localizers - new and experienced - in the context of the type of content that SUMO presents in its many available locales.

A style guide is the document that everyone using a locale should refer to. It is the golden standard of localization for the locale.

It is possible that your locale already has a style guide created by localizers who worked in your language before you.

It is also possible that you will be involved in creating a style guide from scratch! It is not a trivial task, but it helps everyone who starts to localize the project after it is created. Creating a style guide is a responsibility of the Locale Leaders and Reviewers.

How to create a style guide

Locale Leaders and Reviewers should cooperate online to make the style guide as broad and definitive as possible. It is a good idea to take an existing style guide (for example from a different project) and base your own style guide on it.

Languages are processes, rather than mathematical constants - so, a style guide should be open for reviews and updates by the community using it, if necessary.

A style guide should be written in the target (native) locale, so that all localizers can understand what it contains, even if they are not experts in the source (English) locale.

What should a style guide include? Some of the categories of information included in a style guide should be:

  • Common types of text

The most popular types of text that are to be localized following the rules of this style guide. SUMO texts are generally divided into two broad categories:

    • “How to” articles - explaining features and options of Mozilla-powered software.
    • “Troubleshooting” articles - explaining common or unusual problems encountered while using the software and proposing solutions to them.
  • Terminology

An explanation of the terms and concepts present in the source and their counterparts in target locales; may include a list of ‘false friends’ (= terms that you think mean one thing, but actually mean another). SUMO terminology is mostly based on the terms gathered in the Transvision tool.

  • Code in the text

An explanation of how code in the text looks like and what should (and should not) be done with it. For example, at SUMO this will include options for displaying different content to different platform configurations (also known as the for tags).

  • Acronyms and abbreviations

All the tricky vocabulary shortcuts we love to use in IT. IYKWIM ;-)

  • Capitalization

Which words are Capitalized. Some terms could even be ALL CAPS!

  • Dates & numbers

Different locales use different formats for dates and numbers. For example 03/04/15 means a different thing to someone from USA, and someone from Spain

  • Whitespaces

The way different parts of text are separated by empty spaces (for example: paragraphs, images, headings)

  • General spelling, grammar, and punctuation

General rules about spelling, grammar, and punctuation in the locale. The basics everyone should know by heart, but that is better to have written down for reference.

Existing style guides

(please add one for your language, if it exists!)

Upcoming style guides

(please add one if you are working on it and need help!)