[📑 Docs]: new style guide - Internalization (i18n) and Localization

[thulieblack]

What Dev Docs changes are you proposing?

Let's finally get around to creating, designing, and incorporating an AsyncAPI Style Guide!

Why the need?

In tech jobs, we often focus on our technology's technical aspects, such as functionality and performance. However, the documentation for our technology is equally important to the code itself. A style guide ensures consistency and clarity, establishes a consistent voice and tone in your documentation, makes it easier for multiple writers to work together on a single doc, and helps ensure documentation is accurate and up-to-date. When all of your technical writers follow the same guidelines, it's easier for readers to find the information they need and understand how to use your product or OSS technology.

What section of the AsyncAPI Style Guide is this issue for?

• Internalization (i18n) & Localization: Docs should meet the language and cultural needs of new regions and multiple locales. (probably a future goal, once AsyncAPI has incorporated i18n)

Where should this go?

Let's create a new .md file for only the Internalization (i18n) & Localization section of the new AsyncAPI Style Guide.

Create the following directory and place your file there: asyncapi.com/docs/community/styleguide/i18n-localization.md.

Extra Resources

• Write the Docs: Style Guides
• Gatsby Style Guide
• Gatsby Docs Structure & Documentation Types
• Mozilla Style Guide
• Google Style Guide
• Microsoft Style Guide

Code of Conduct

• [x] I agree to follow this project's Code of Conduct

[rohithyarramala]

AsyncAPI Internationalization (i18n) & Localization Guide

Introduction

As AsyncAPI grows into a global community, creating documentation that is accessible and culturally sensitive becomes crucial. This guide provides recommendations for making our documentation inclusive and adaptable to different languages and cultural contexts.

Key Principles of Internationalization

1. Language Considerations

• Write content in clear, simple English that can be easily translated
• Avoid idiomatic expressions, colloquialisms, and region-specific references
• Use straightforward sentence structures
• Minimize complex grammatical constructions

2. Cultural Sensitivity

• Remove cultural references that may not translate or be understood globally
• Be mindful of cultural nuances in communication
• Avoid humor or jokes that might not translate well
• Use neutral, professional language that resonates across different cultures

Localization Best Practices

Translation Preparation

• Use consistent terminology throughout documentation
• Create a centralized glossary of technical terms
• Provide context for translators
• Design documentation with translation in mind (e.g., leave space for text expansion)

Structural Considerations

• Ensure documentation layout supports right-to-left (RTL) and left-to-right (LTR) languages
• Use flexible design that accommodates varying text lengths
• Avoid hard-coding text within code examples or graphics

Technical Implementation

• Use internationalization (i18n) frameworks and tools
• Support Unicode and multi-language character sets
• Implement language-switching mechanisms
• Store translatable strings separately from code

Recommended Tools and Resources

• Translation management systems
• Professional translation services
• Open-source translation platforms
• Collaborative translation tools

Future Implementation Steps

1. Establish a translation review process
2. Create a community translation program
3. Develop guidelines for community translators
4. Implement translation quality assurance mechanisms

Accessibility and Inclusivity

• Ensure translations maintain the spirit of AsyncAPI's inclusive language guidelines
• Provide translations that are culturally appropriate and sensitive
• Consider regional technical terminology variations

Measuring Translation Quality

• Implement user feedback mechanisms for translations
• Conduct periodic translation quality reviews
• Use community input to continuously improve localized documentation

Contribution Guidelines

• Provide clear instructions for community members who want to contribute translations
• Create a transparent and collaborative translation workflow
• Recognize and credit translation contributors

Note: This guide is a living document and will evolve as AsyncAPI's international community grows.

[rohithyarramala]

hello @thulieblack , i want to work on it. and done some work you can check above , if you agree i will raise a pr. with it.

[thulieblack]

@rohithyarramala you neeed to complete the TW checklist first and the style guide before jumping to contributing docs

[CBID2]

Hi @thulieblack. I can work on this issue.

[thulieblack]

go ahead @CBID2