WordPress.org
Get WordPress

Style Guide Creation Workshop

Goals:

After this lesson, you should be able to: 

  • Learn what is a style guide and why & when you need it.
  • Understand the process of creating a style guide for your locale team.
  • Figure out what rules should be included in your style guide.
  • Complete a style guide document that can help contributors achieve consistent and high-quality translation across the project.

Audience:

  • Translation editors (as project leads)
  • General Translators (as collaborators)

1: Intro/Overview

(10 minutes)

Why and when do you need a translation style guide?

Think of a style guide as something like this for translation.

  • Coding standards
  • Writing guidelines/manual
  • Design & UI style guide/guidelines

Without these guidelines, a team of contributors may still be able to create software, document, or visual design that serves their original purpose. However, the end results will likely be less consistent and refined than the work based on a solid guideline.

Also, ambiguous feedback discourages contributors because it’s hard to make improvements if they don’t know exactly how to do so. By creating a style guide that is agreed upon by the team, you can reduce unnecessary rework and arguments over personal preferences.

As a GTE or PTE, if you find yourself correcting similar mistakes more than a few times, it’s probably a good time to start building a style guide.

If you haven’t gone through section 1 (Intro/Overview) of the Glossary Creation lesson plan, we recommend doing so and coming back.

2: Mini-work #1

(5 minutes)

Find a link to a translation/writing style guide for other projects or publications in your language.

In most cases, the best way to search for an example of a style guide is to use the keyword “translation style guide” or “translation guideline” in your language. If you can’t find any translation style guide, try just “style guide” or “writing style guide”.

After you find one, look through it – are there rules that can be helpful to have in your team’s WordPress translation style guide?

If you still can’t find any good examples in your language, you may want to check out the WordPress Documentation Team’s Style Guide (English) instead.

3: Style Guide Contents/Structure

(10 minutes)

You may wonder what kind of information a translation style guide usually contains. Typically, rules that fall under these sections are included:

  • Introduction
  • Formality/Tone
  • General Rules
  • Vocabulary
  • Punctuation, Syntax, and Formatting
  • Types of Messages and Placeholders
  • Additional resources

The details of each section are explained on the Style Guide Template handbook page.

You don’t have to include everything in the above list, especially in the beginning. We recommend that you get some ideas from the examples and start figuring out the most important rules to introduce for your locale.

4: Mini-work #2

(5 minutes)

Select 3 (or more if you have time) high-priority rules you think should be in your locale’s style guide, and explain how they should be translated.

You can try:

  • Thinking of frequent mistakes you keep correcting
  • Looking through the translation of WordPress core and select the unique rule that is particular to the WP project
  • Searching for rejected translations using the filter on translate.wordpress.org

If there are multiple translators from the same locale, try to work together.

5: Deciding on What Translation Rules to Add

(10 minutes)

You want to prioritize any rules that can:

  • Reduce the confusion among translators 
  • Contribute to improved consistency and quality

The style guide building process sometimes gets blocked when team members have conflicting opinions on what rule to follow and can’t come to an agreement. This is actually a great opportunity to discuss a rule in detail and build a consensus within the team. It’s important that the team members are able to give and receive feedback with respect to each other and work together.

Use one or more of the method(s) explained in sections 5 and 7 of the Glossary Creation workshop, and keep repeating the process.

6: Recap

(5 minutes)

Basically, repeating these will eventually build a good style guide of your own.

  1. Find translations that tend to be inconsistent 
  2. Come up with a rule that prevents the inconsistency
  3. Present it to your team and have them approve the rule and the description
  4. Add it to your style guide document

7: Mini-work #3

(5 minutes)

What’s your next action plan?

For example:

  • Publish the style guide framework document on your Rosetta site or Team Handbook
  • Regularly post to Team P2 about suggestions of new rules to add to the style guide
  • Meet with your team once a month to run some of the mini-work you learned during this workshop