chore: Updated translation guide
This commit is contained in:
joostdecock
parent
cf7a882744
commit
69ca2af3dd
1 changed files with 187 additions and 64 deletions
|
|
@ -2,102 +2,217 @@
|
||||||
title: Translation guide
|
title: Translation guide
|
||||||
---
|
---
|
||||||
|
|
||||||
FreeSewing is proudly multilingual, and we currently support five languages.
|
Supporting multiple languages is one of the best way to promote inclusion and
|
||||||
For this, we rely on the work of our translators who volunteer their
|
accessibility. Thanks to the efforts of our community, FreeSewing is proudly
|
||||||
time to translate FreeSewing into various languages from English, which
|
multilingual.
|
||||||
is our source language.
|
|
||||||
|
|
||||||
This translation guide will tell you everything you need to
|
This translation guide covers everything you need to know to join the effort of
|
||||||
know to join the effort as a translator for FreeSewing.
|
translating FreeSewing into other languages.
|
||||||
|
|
||||||
<Tip>
|
## Supported Languages
|
||||||
|
|
||||||
##### TL;DR: Becoming a FreeSewing translator
|
|
||||||
|
|
||||||
Our translation project on Crowdin is accessible
|
|
||||||
via [translate.freesewing.org](https://translate.freesewing.org).
|
|
||||||
|
|
||||||
To get started, you will need to be invited as a translator. No need to worry,
|
|
||||||
simply [let us know you'd like to help out](https://discord.freesewing.org/) and we'll add you.
|
|
||||||
|
|
||||||
For access to Strapi, you will need an account on [our Strapi instance](https://posts.freesewing.org/).
|
|
||||||
Here too, [Discord is the place to let us know you'd like to help out](https://discord.freesewing.org/).
|
|
||||||
|
|
||||||
Bonus: You'll get an `@freesewing.org` email alias
|
|
||||||
|
|
||||||
</Tip>
|
|
||||||
|
|
||||||
## Languages
|
|
||||||
|
|
||||||
We currently support the following five languages:
|
We currently support the following five languages:
|
||||||
|
|
||||||
- **en** : English
|
- **en** : English <small>(This is our source language and the working language
|
||||||
|
of the FreeSewing project)</small>
|
||||||
- **de** : German
|
- **de** : German
|
||||||
- **es** : Spanish
|
- **es** : Spanish
|
||||||
- **fr** : French
|
- **fr** : French
|
||||||
- **nl** : Dutch
|
- **nl** : Dutch
|
||||||
|
|
||||||
<Note>
|
## Incubator Languages
|
||||||
|
|
||||||
If you'd like to start working on a new language, that's great, but a bit
|
For the following languages, our community has started an effort, but that
|
||||||
beyond the scope of this documentation. Before you start working on a new language
|
effort has not yet reached the level of maturity that to make it a supported
|
||||||
please [come and talk to us on Discord](https://discord.freesewing.org).
|
language.
|
||||||
|
|
||||||
</Note>
|
In other words, **these are the languages where we are most in need of extra
|
||||||
|
translators**:
|
||||||
|
|
||||||
## Translation in Crowdin vs Strapi
|
- **uk** : Ukranian
|
||||||
|
|
||||||
We use two different tools to manage our translations, depending on the context:
|
## Become a FreeSewing translator
|
||||||
|
|
||||||
- Markdown content and code strings in our monorepo are translated within **Crowdin**
|
To gain access as a FreeSewing translator, you will need an invite.
|
||||||
- Blog and showcase posts are translated within **Strapi**
|
|
||||||
|
You can __[request a translator invite
|
||||||
|
online](https://next.freesewing.org/translation/join)__ and we will send you an
|
||||||
|
invite with all further instructions.
|
||||||
|
|
||||||
|
<Fixme compact>This link above still needs to be implemented in the new v3
|
||||||
|
website</Fixme>
|
||||||
|
|
||||||
|
We also have [a dedicated __Translation__ channel on
|
||||||
|
Discord](https://discord.freesewing.org) for any questions that may remain.
|
||||||
|
|
||||||
|
## Adding a new language
|
||||||
|
|
||||||
|
We would love to make FreeSewing available in more langauges. If you are
|
||||||
|
interested in starting a new translation effort, that is great.
|
||||||
|
|
||||||
|
We ask that you familiarize yourself with this translation guide to understand
|
||||||
|
what it takes to add a new language. Then if you want to start a new language,
|
||||||
|
you can get the ball rolling by completing this online form.
|
||||||
|
|
||||||
|
|
||||||
|
<Fixme compact>
|
||||||
|
This link above still needs to be implemented in the new v3 website
|
||||||
|
</Fixme>
|
||||||
|
|
||||||
<Tip>
|
<Tip>
|
||||||
|
|
||||||
##### Translation priorities
|
##### Get the band together
|
||||||
|
|
||||||
If you'd like to help out, please join our translation team on Crowdin.
|
We recommend finding some like-minded people who can help translating.
|
||||||
|
|
||||||
While it can be nice to have blog and showcase posts translated, these are less important than the
|
While the core materials of FreeSewing can realistically be handled by one
|
||||||
translation work in Crowdin which is about the documentation and strings that allow people to
|
person, translating all of FreeSewing's documentation and content realistically
|
||||||
use FreeSewing in a different language.
|
is a job you should not undertake on your own.
|
||||||
|
|
||||||
</Tip>
|
</Tip>
|
||||||
|
|
||||||
### Crowdin
|
<Comment by="joost" >
|
||||||
|
|
||||||
Most translation happens in Crowdin ([crowdin.com](https://crowdin.com/)), an online translation platform
|
##### Do or do not. There is no try.
|
||||||
that makes translation and collaboration a breeze.
|
|
||||||
|
|
||||||
In Crowdin, all text is broken up into lines, words, or paragraphs that are then translated.
|
There is a certain cost to adding a new language. It's not a cost in money,
|
||||||
This not only facilitates collaboration — as rather than work on one large block of text,
|
but rather in increased bandwidth, storage requirements, build times,
|
||||||
various people can jump in and translate smaller snippets — it also enforces a strict one-to-one
|
repository size, test times, and so on.
|
||||||
match between the English source material and the translation.
|
|
||||||
|
|
||||||
This strict correlation is important. People who refer to the documentation in a different language
|
It's a cost we are __more than happy__ to pay for the benefit gaining another
|
||||||
expect to find the same structure, the same amount of headings, paragraphs, and so on.
|
langauge. But it is also a cost that needs to be paid up front, at the start
|
||||||
|
of the effort.
|
||||||
|
|
||||||
### Strapi
|
So, without wanting to discourage anyone, I would really like to avoid a
|
||||||
|
scenario where people enthusiastically start working on a new languages, only
|
||||||
|
to lose interest days or weeks later and see the effort falter.
|
||||||
|
|
||||||
Strapi ([strapi.io](https://strapi.io/)) is a so-called _headless content management system (CMS)_.
|
With that out of the way, I hope to see many more languages being added in the
|
||||||
"_Headless_" just means that we load the content from it via an API, rather than have it be part of our
|
future.
|
||||||
website like a classic CMS (eg. Wordpress).
|
|
||||||
|
|
||||||
In Strapi, we keep our blog posts and showcases for freesewing.org.
|
</Comment>
|
||||||
We also keep our newsletter editions and developer blog posts for freesewing.dev there, but since
|
|
||||||
those are not translated, we will ignore them in this guide.
|
|
||||||
|
|
||||||
Strapi supports different language versions for posts, but it's not a translation system like Crowdin
|
## Translation status
|
||||||
that breaks text down into small parts to translate.
|
|
||||||
Instead, each post can be translated as a whole, and there is no enforcement whatsoever of structure or
|
|
||||||
content between the versions for different language.
|
|
||||||
|
|
||||||
In other words, a translated blog post could use a different structure or even different images.
|
The status of the ongoing translation work is available at
|
||||||
This is by design, because we want to encourage the different (non-English) FreeSewing communities
|
[FreeSewing.org/translation](https://freesewing.org/translation).
|
||||||
to make FreeSewing their own, by writing blog posts that are relevant or specific to them.
|
|
||||||
|
|
||||||
This also means that English does not have to be the source language in Strapi.
|
It's a good place to check what languages need extra help, and which are
|
||||||
Somebody could write a French blog post (for example) which can then be translated to English.
|
leading the scoreboard.
|
||||||
|
|
||||||
|
## Content types and translation priorities
|
||||||
|
|
||||||
|
To fully translate FreeSewing, the following types of content needs to be
|
||||||
|
translated:
|
||||||
|
|
||||||
|
**Top priority: UX Translations** These are translations the directly impact
|
||||||
|
the user experience (_UX_). They include the content used in design, the names
|
||||||
|
of options, translations of menus, emails, and so on.
|
||||||
|
|
||||||
|
This is a relatively small amount of text, and makes up less than 10% of the
|
||||||
|
top & high priority content. It's an effort that a motivated translator can
|
||||||
|
complete over the course of a weekend.
|
||||||
|
|
||||||
|
**High priority: Translation of Documenation** This includes all the
|
||||||
|
documentation on FreeSewing.org.
|
||||||
|
|
||||||
|
This is a significant amount of text that makes up more than 90% of hte top *
|
||||||
|
high priority content. It's an effort you should probably not take on by
|
||||||
|
yourself, but rather tackle with a team of translators.
|
||||||
|
|
||||||
|
**Low Priority: Content of blog and showcase posts** This is
|
||||||
|
_nice to have_ as people can use and navigate FreeSewing even when this content
|
||||||
|
remains untranslated.
|
||||||
|
|
||||||
|
Still, if you are considering translating this content, you might want to
|
||||||
|
consider the following priorities within this categors:
|
||||||
|
|
||||||
|
- First: Showcases posts. Not only do they typically have less text, their
|
||||||
|
value is also less tied to how recent they are
|
||||||
|
- Then: Blog posts. Start with the most recent onces. How older a blog post
|
||||||
|
gets, the less relevant it becomes
|
||||||
|
|
||||||
|
## Translation through Crowdin
|
||||||
|
|
||||||
|
All of our top-priority and high-priority translation work is handled through
|
||||||
|
[Crowdin](https://crowdin.com/), an online platform to facilitate translation.
|
||||||
|
|
||||||
|
<Tip compact>
|
||||||
|
|
||||||
|
You can reach the FreeSewing project on Crowdin directly via
|
||||||
|
[translate.freesewing.org](https://translate.freesewing.org).
|
||||||
|
</Tip>
|
||||||
|
|
||||||
|
Crowdin is configured to automatically detect all of the various translation
|
||||||
|
files in our repository, upload them to the platform, and break them apart into
|
||||||
|
bite-sized portions that you can translate in a collaborative way.
|
||||||
|
Rather than work on one large block of text, various people can jump in and
|
||||||
|
translate smaller snippets,
|
||||||
|
|
||||||
|
Once translated, there is a proofreading step that will be handled by one of
|
||||||
|
our proofreaders. This is often a formality, but it's an extra step to allow
|
||||||
|
qulity assurance and avoid any mistakes from slipping in. Much like the code
|
||||||
|
review process when you submit a pull request on GitHub.
|
||||||
|
|
||||||
|
Once your translation is approved, Crowdin will automatically submut a pull
|
||||||
|
request on GitHub to update the translation files in our repository. And the
|
||||||
|
next time our website or software packages get build, they will include the new
|
||||||
|
translations.
|
||||||
|
|
||||||
|
<Note>
|
||||||
|
|
||||||
|
##### Priorities of translations in Crowdin
|
||||||
|
|
||||||
|
- The top-priority translations in Crowdin are everything under the `packages`
|
||||||
|
and `sites` folder. Do this first.
|
||||||
|
- The high-priory translations in Crowdin is everything under the `markdown`
|
||||||
|
folder.
|
||||||
|
|
||||||
|
</Note>
|
||||||
|
|
||||||
|
## Translation through Sanity
|
||||||
|
|
||||||
|
Sanity ([sanity.io](https://sanity.io/)) is a so-called _headless content
|
||||||
|
management system (CMS)_. "_Headless_" just means that we load the content
|
||||||
|
from it via an API, rather than have it be part of our website like a classic
|
||||||
|
CMS (eg. Wordpress).
|
||||||
|
|
||||||
|
In Sanity, we keep our blog and showcases posts for freesewing.org.
|
||||||
|
In other words, **Sanity only holds the low priority translation work**.
|
||||||
|
|
||||||
|
<Tip compact>
|
||||||
|
|
||||||
|
You can reach the FreeSewing project on Crowdin directly via
|
||||||
|
[translate.freesewing.org](https://translate.freesewing.org).
|
||||||
|
</Tip>
|
||||||
|
|
||||||
|
<Note>
|
||||||
|
|
||||||
|
##### Why we don use Crowdin for blog/showcase translations
|
||||||
|
|
||||||
|
Crowdin enforces a strict one-to-one match between the English source material
|
||||||
|
and the translation.
|
||||||
|
|
||||||
|
This strict correlation is important for the UX and documenation transaltions.
|
||||||
|
People expect a menu to have the same structure in all languages, and when we
|
||||||
|
refer to the documentation we need to ensure that those links works for all
|
||||||
|
languages, which requires that all languages use the same structure, the same
|
||||||
|
amount of headings, paragraphs, and so on.
|
||||||
|
|
||||||
|
Sanity supports different language versions for posts, but it does not enforce any structure on them.
|
||||||
|
A translated blog post could have more or less paragraphs, different images, you name it.
|
||||||
|
|
||||||
|
This additional freedom is why we use Sanity for these types of content. We lik
|
||||||
|
to encourage the non-English FreeSewing communities to make FreeSewing their
|
||||||
|
own, by writing blog posts that are relevant or specific to them, or
|
||||||
|
translating blog posts not merely word-for-word, but making them relevent to
|
||||||
|
their language group.
|
||||||
|
|
||||||
|
This also means that English does not have to be the source language in Sanity.
|
||||||
|
Somebody could write a French blog post (for example) which can then be
|
||||||
|
translated to English.
|
||||||
|
|
||||||
|
</Note>
|
||||||
|
|
||||||
## Syntax
|
## Syntax
|
||||||
|
|
||||||
|
|
@ -131,3 +246,11 @@ looks like this in Spanish
|
||||||
```yaml
|
```yaml
|
||||||
{field} guardado
|
{field} guardado
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Questions, Suggestions, Discussion
|
||||||
|
|
||||||
|
If you have questions, suggestions, or would like to discuss
|
||||||
|
translation-related matters, please join
|
||||||
|
[discord.freesewing.org](https://discord.freesewing.org/) and head to the
|
||||||
|
__Translation__ channel.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue