Style Guides

Style Guide Working Group Basics

Style Guide Working Group Notes
Style Guide Discussion in SecureDrop Forum
Localization Lab Style Guide in framaGit

Style Guide References

Mozilla Style Guide
Fedora Style Guide
GNOME Style Guide

Generic Style Guide

Language & Terminology

Glossary

Use the glossary! The glossary is one key way to keep translations high quality and consistent. Make sure to reference the glossary throughout your translation and review and regularly update it. The glossary is particularly important when it comes to neologisms and technical terminology which in several languages have not yet been standardized.

Glossary in Transifex: You will find relevant glossary terms listed on the “Glossary” tab in the translation editor. If a term is not listed in the glossary that should be, you can add it by selecting “Add term”.

[Add screenshot]

If you would like to add a translation to a term or would like to edit the translation of a term, you will need to select “View Glossary” to search for and edit the term within the Glossary interface.

[Add screenshot]

Glossary in Weblate: [Input instructions for interacting with Weblate glossary. Recommend using glossary in Transifex as reference instead of using the Weblate one.]

Global v. Regional Language

Use language that is as “neutral” as possible. What does this mean? Try not to use regional references, vocabulary, grammar and idiomatic expressions that could exclude speakers from a different region or country. Aim to use language that is more global than regional.

Project Names and Proper Nouns

Do not translate project names or proper nouns unless there is already a widely accepted translation of the proper noun or project name. In the case of project names, this translation should be approved by the project developers.

United Nations -> Naciones Unidas (Spanish), الأمم المتحدة (Arabic)
Tor -> تور (Arabic)

If speakers of your language need proper nouns and project names transcribed into your language, you can place the transcription in parenthesis after the original project name or pronoun.

Psiphon -> Psiphon (سايفون)

Voice, Tone & Style

Tone

The majority of projects supported by the Localization Lab community use an informal, personal tone in English. You do not have to replicate this tone if it is not appropriate in your language. If users in your language will respond better to a formal tone, feel free to use one. You can also refer to tools already in wide use in your language (localized social media platforms, office tools, software and websites) to determine what tone will be most comfortable for users.

Voice

Use of active / passive language for example.

Misc.

Variables

Do not change variables! What is a variable? A variable is a placeholder that will be replaced with a word or number within the application.

For example, a source string may contain the following:

You may not have an application able to open this url: %s.

And produce the following in the application

You may not have an application able to open this url: www.psiphon.ca.

Markup Language

Retain markup language in source strings. What is markup language? Markup language is a way of annotating a document or text to provide information about how text should be structured or presented. In Localization Lab supported projects you will most often find HTML (Hypertext Markup Language) used to enrich text.

For example, a source string may contain the following:

Choosing the default < strong >“Fastest Country”< /strong > option allows Psiphon to automatically choose a server, which will generally result in the best network connection.

Which will produce the following in the final application:

Choosing the default “Fastest Country” option allows Psiphon to automatically choose a server, which will generally result in the best network connection.

Note: Transifex replaces Markup Language with placemarkers in the web interface. In order to transfer the placeholders to your translation, all you need to do is select the placemarker from the source text and it will appear in the translation text. You can also copy-paste the placeholder into the source text.

If you prefer working with the raw Markup Language, you can select the settings icon in the Transifex Web Editor, select Editor Preferences and then toggle “Enable raw editor mode” on.

[Add screenshots]

Unicode

Use Unicode by default! If your language uses non-unicode fonts, be sure to contact Localization Lab staff prior to localizing a tool so that we can ensure that the tool you are working on can display the font of your choice.

System References

Applications will often reference text in the device’s operating system (iOS, Android, macOS, Windows etc.). Be sure to use the terminology used in the system localizations. If no system localization exists, use the original term in English with a translation following in parenthesis.

[Add example]

If buttons, options, drop downs from the application are referenced in a string, be sure to double check the translation in the application to ensure that it is consistent.

[Add example]

Language Team Style Guide Template

Voice, Style and Tone

Tone

Should the tone of the translation be formal? Or informal?
What do the target users expect in your language?
What kind of tone do other popular localized tools use?

Voice

Active or passive voice? (This may be more or less relevant depending on the language) Regional v. Global: In your language, do cultural references, idioms, slang and general terminology vary widely based on region or another

Grammar

Punctuation

Does the language have any particular punctuation conventions that should be kept in mind? For example, in French, a space is placed before a colon or “deux-points”:

Par exemple, en français, un espace est placé avant un deux-points :

And “guillemets” (« ») and “atirets” (em-dashes) are used in place of quotation marks “” within a conversation.

[Provide] example

Terminology

Creating New Terminology

Please overview how new terms are created in the language, particularly technical neologisms. There is a wealth of new terminology used in the tools supported by the Localization Lab as well as well established technical language that has yet to be standardized in different languages. Defining a clear approach for creating terminology in a language will ensure that all of these technical terms remain consistent across all related digital security and circumvention tools supported by the Localization Lab community. Confusion over terminology could result in misuse of a tool, putting the user in as much or more danger than without using the tool.

• Does the language borrow words? If so, from which languages? Does the language borrow different types of terms from different languages?
  
• Does the language literally translate words instead of borrowing them?
  
• Does the language create new words based on regional context?
  
• Are there other tools that might contain the term you cannot find? Think about which localized tools are most popular across your target audience. This could mean referencing popular social media platforms, document managers or websites.
  
• Are there languages similar to your language whose terminology creation process you can reference? For example, if you are a speaker of a Celtic language (Welsh, Irish Gaelic, Scottish Gaelic, Breton etc.) can you refer to existing translations in a language from the same family to learn from how they have borrowed or created the term?

Numerals and Units

Numerals

What numeral system does the language use?

Units

Should units for this language be in the Metric, Imperial or another system?

References

Localized Tools

What popular tools exist that are already localized into your language? Are there any open source, digital security and / circumvention tools that you can reference for difficult terminology?

Dictionaries and Glossaries

What technical glossaries and dictionaries exist that can be used as reference for localization?