rOpenSci Localization and Translation Guidelines

Why and how we localize and translate our resources.

Author

Yanina Bellini Saibene, Paola Corrales, Elio Campiteli, Maëlle Salmon

Preface

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 a university 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 their university. They read the Spanish version of the book “rOpenSci Packages: Development, Maintenance, and Peer Review” to prepare their 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 Brazil. 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 R as our main programing language and 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. 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.

You can cite this book:

rOpenSci Localization and Translation Guidelines v1.0. Yanina Bellini Saibene, Paola Corrales, Elio Campiteli, Maëlle Salmon (November, 2023)

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 License.

Thanks!

You can also read the PDF version of this book.

Attributions

These translation guidelines are based on the experience and documents generated during the translation of Teaching Tech Together.