📑 What is a style guide?
In the most general sense, it is a document in which the developer or product owner shares context about the software together with expectations towards localization.
So a style guide should at least say:
- what your software does
- who are the potential users of your application
- who are you, as a developer, and what is your mission, goal, etc.
This is the most basic information you should include in your style guide. It should give background and context to your software. All translators LOVE 💖 to have context and the more you provide - the better. Context makes localization work a lot easier for you - the developer, and them - translators and reviewers.
Why for the developer? Because as a developer, you will not be answering the same boring questions all the time. All of it will be neatly prepared in one document.
Why for translators? Because they will not have to ask the most basic questions, as all initial context would be delivered in a neat document.
You can save a significant amount of time, for all parties, by providing this context in the style guide at the beginning of the localization process. The only challenge is to deliver a well prepared style guide up front.
How to prepare a style guide for your software project's localization?📚 What should a well prepared style guide contain?
The more of the elements below that you include, the better, and of course you can add even more. There is no such thing as too much context! Below you will find some examples of what to include in your style guide.
What is your organization or brand?Introduce your brand to translators, for example like this:
"Since the launch of Kikiriki Software in 2010, the team has expanded from 1 ambitious college student to 800+ full-time employees. Kikiriki offers the only visual collaboration suite that helps teams see and build the future from idea to reality."
What product and/or services are being localized?Provide a brief description of the product or services that you provide, it could look like this:
"Kikiriki is a virtual whiteboard application for freeform ideation, group brainstorming and real-time collaboration across teams."
Resources for your software- Is there a trial available?
- Do you have a glossary of the most important terms used in your UI?
- URLs, YouTube videos with software use cases.
- Any online presentations of your software?
- Do you run a Discord channel?
Learn more about Glossary management in LocalazyGlossary of terms helps provide context for translators. What is the tone of the texts used to present your products?
- Are colloquial expressions allowed/required/disallowed?
- Active/passive voice?
- Abbreviations - yes/no?
- Website names
- Brand names
- User names
- Product names
- Email addresses
- URLs
- Any characters/character types unsupported in UI?
- Begin each bullet point with a capital letter?
- If a bullet point is a complete sentence, end each bullet point with a period?
- Use active voice; passive voice should be avoided.
- Pronoun for the company is a singular "it" and not plural "them"..
- Write in 1st person to customers, e.g., “your downloaded files”.
- Write directly as a company when possible, e.g., “We weren’t able to retrieve your document. Please try again.”
- Be lighthearted, but not overly humorous; phrases like “Oopsie!” and “The gremlins are on it right now” are not allowed.
These are just examples of information I find useful. The above saves me a lot of time, as prior to localizing your software I would have to find your website and FB/Twitter/Instagram profiles or other online resources. Then I would start looking for general information about the company and the product to be localized. I would then have to make sure that I found the right data, so I would most probably message you several times to confirm my research and ask some more questions.
This would take significant amount of time (yours and mine). With a style guide you would have just saved me at least 2-3 hours of getting familiar with the most general context of what your company is and what the software is that you create.
Now comes the best part - if you localize your software to many languages, this one style guide can be provided to all your translators with information that is equally useful for all of them.
✏️ One style guide for all languages?
That would be too beautiful. The above information is indeed extremely useful for all languages but there are always language specific quirks that mean there will be a huge benefit to more information.
Therefore, you can also prepare a language-specific section of your style guide that would contain precise linguistic requirements. Here you would need to provide diverse rules that most probably will be different for each language. This pays back even more then the general part of the style guide. As you get then a manual describing all the do’s and don'ts when translating your software to a given language.
Linguistic rules differ from language to language and your software should be adapted independently to them. There is no golden localization guide for all languages.
📌 So again, why should I create and maintain a style guide?
- This saves time, a lot, overall in the whole process.
- Makes your localizations coherent in terms of style and language.
- Introducing/changing translators/reviewers is not a problem - the on-boarding is much smoother and quicker when they get a set of localization rules at the very beginning.
- Ask for and introduce in your style guide suggestions from your contributors.
📰 Further reading
This is a companion discussion topic for the original entry at https://localazy.com/blog/linguistic-style-guides-software-localization