rOpenSci Translation Guidelines

Why and how we localize and translate our material.

Preface

Note

You are reading the first edition in progress of the rOpenSci Localization and Translation Guide. This chapter is almost complete, but information still needs to be added and just needs one last revision.

Welcome!

This book explains all the steps and tools involved in the localization of our materials, including translations. We design, build, and test a process for maintain the different languages version of our materials that take ideas from our software peer review system and the maintenance of open-source projects.

We know that code peer review ensure the quality of our software; with the same goal of ensuring the quality of our content in different languages, we implement a system to review and maintain the localization of our guides, books, blog post, and other content.

We also know that by using roles (such as reviewers and maintainers) and tools (such as GitHub and Pull Request) known to our community, we make this process easier to undestand, apply and, therefore, easier to contribute to.

Intended Audience

This book is a guide for people who would like to localize rOpenSci materials or contribute to maintaining localized material. It is also intended for people that have to localize material on other community or group. You don’t need to be a proffesional translator or developer to contrinute to this effort. The following personas are examples of the types of people that are our target audience.

Ana

is a Colombian student doing her Ph.D. at FAMAF in Argentina. She works with geospatial data. She is not an expert in programming, but she took one of The Carpentries workshops for scientists and used some of the rOpenSci suite packages for handling and accessing geospatial data for her thesis. Language was one of the barriers she faced when learning to code. Ana wants to contribute by translating material into her native language so others can access this knowledge with less effort. This book will show her how to do a new translation and how to review an existing one.

Francesco

will send their packages to the rOpenSci review process in Spanish. They know that this will ensure the quality of their software and will also facilitate its publication in JOSS, which will give them academic credit for their job at Universidad Mayor de San Andrés in Bolivia. They read the Spanish version of the book for development and a peer-review package to prepare the submission. If their review experience is good, they will volunteer to be a reviewer in their native language and contribute to the book. This guide will explain how to become a contributor and maintainer of translated material and the infrastructure that allows translations.

Bauti

is the co-founder of a user group in his city in Chile. With a couple of university classmates, he teaches and learns together how to code and do reproducible analysis using different languages. He uses rOpenSci Spanish material during his workshops and would like to have the material from other programming languages in Spanish. He wonders how rOpenSci manages translation. This book will show him how we organize translation and what tools we use so that he can apply in his community.

What You Will Learn

The guide contains:

• Why we localize, translate and work to do multilingual publishing.
• General guide with the infrastructure and roles, step-by-step technical process, and localization considerations, including the technical terms to translate and the technical terms we will not translate.
• Language-specific guides with localization considerations.
• Language-specific glossary.

At rOpenSci, we use GitHub to host our code, including our packages, books, webpage and review process. The step-by-step technical process refers to working with GitHub, like making pull requests, reviewing and commenting on pull requests, and creating issues. It also explains how to use the {babeldown} R package that facilitates working with translations.

The localization consideration and the glossary are language-specific and detail the agreements the community reach about how to localize and translate the material. This chapter is different for each language present in this guide.

We hope that you’ll find the guide useful and clear, and welcome your suggestions in the issue tracker of the book. Please check Contributing and Re-Use section to learn more about hot to contribute.

Happy localization!

Contributing and Re-Use

This book is a living document. You can view our best practices and policies updates via the release notes.

You can cite this book using its Zenodo metadata and DOI.

<FIXME: Add cite here>

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License.

If you want to contribute to this book, corrections, additions, and suggestions are very welcome. Everyone whose work is included will be credited in the acknowledgments. Please refer to the GitHub repository, particularly the contributing guidelines and our Code of Conduct, for more information on how to contribute.

Thanks!

You can also read the PDF version of this book.