Skip to content

Commit 60df867

Browse files
prathersprathers
authored
Add Bestpractice.rst (#6184)
* Add Bestpractice.rst * Improvements after QA
1 parent 9d4f55a commit 60df867

File tree

2 files changed

+304
-0
lines changed

2 files changed

+304
-0
lines changed

‎Documentation/ApiOverview/Localization/TranslationServer/Crowdin.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Localization with Crowdin
2121
Crowdin/ExtensionIntegration
2222
Crowdin/OnlineTranslation
2323
Crowdin/Workflow
24+
Crowdin/Bestpractice
2425
Crowdin/Faq
2526

2627
.. _xliff-translating-server-crowdin-what-is:

‎Documentation/ApiOverview/Localization/TranslationServer/Crowdin/Bestpractice.rst‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
.. include:: /Includes.rst.txt
2+
.. index:: Crowdin; Best Practice
3+
.. _crowdin-bestpractice
4+
5+
6+
================================
7+
Crowdin Best Practice
8+
================================
9+
10+
.. contents::
11+
:local:
12+
:depth: 2
13+
:
14+
15+
Crowdin offers a wealth of settings and views, which make the work of translating a
16+
process where the meaning of the individual words and phrases really comes into focus.
17+
It is a tool that not only helps you get a handle on the translations, but also to
18+
ensure that everything makes sense in the chosen language. One of the biggest
19+
advantages of Crowdin is that you can work both quickly and efficiently, while
20+
also giving you the opportunity to go in-depth with the language and nuances that
21+
professional translations require.
22+
23+
With a good basic setup of your Crowdin interface, the work will be less nerve-wracking,
24+
and you will find that you get a lot done. It often pays to invest time in customizing
25+
your personal settings in Crowdin so that you get the most out of the features the
26+
tool offers. For example, you can sort and filter files, choose from different
27+
views, and easily navigate between projects. You can also customize the editor
28+
to suit your work style, and leverage or change hotkeys to optimize workflow.
29+
30+
.. note::
31+
Crowdin has a very well-developed help and an active development environment,
32+
where improvements and changes are regularly made that can affect features
33+
and screenshots. Therefore, we prefer to link to Crowdin's own help pages
34+
rather than maintain an actual help section for Crowdin in TYPO3's documentation,
35+
as it ensures that you always have access to the latest and most up-to-date
36+
information.
37+
38+
39+
.. _crowdin-bestpractice-get-started:
40+
41+
Get started with Crowdin
42+
========================
43+
44+
Below you will find a few tips and recommendations that will hopefully inspire you
45+
to make TYPO3 available to many more users – in their own language. Translating
46+
TYPO3 is not only about making the system usable for more people, but also an
47+
opportunity to strengthen the community and collaboration across countries and
48+
cultures. The more people who contribute, the better the quality of the translations
49+
and the overall experience for all users.
50+
51+
The recommendations are divided into some general sections. First, there are a
52+
few general considerations before you start translating a project. Then follows
53+
concrete recommendations and practical tips for working in Crowdin if you want
54+
to translate. Finally, tips and recommendations are presented for you who need
55+
to validate translated words and strings so that you can ensure a consistent and
56+
high quality.
57+
58+
TYPO3 has already organized projects and files in a way that follows Crowdin's
59+
own recommendations. However, as a translator, there will be settings and working
60+
methods that you can adapt to your own needs. This gives you flexibility and the
61+
opportunity to work in the way that suits you best – whether you prefer to translate
62+
directly in Crowdin, whether you use EXT:Crowdin, or if you want to work offline
63+
and upload the files later.
64+
65+
.. _crowdin-bestpractice-initial:
66+
67+
Initial considerations
68+
----------------------
69+
70+
Before you start translating a project, there are some initial considerations that
71+
may be good to consider. For example, start with a project that has a smaller
72+
number of words and strings. This makes the work more manageable and increases
73+
the joy of finishing a project, so you avoid getting completely worn out. It's
74+
important to choose a project that motivates you so that you stay engaged.
75+
76+
A good idea is to start by translating a single file in a project. The different
77+
files are often used in different parts of an extension, and it is easier to
78+
understand the context if you work with individual files. This will help you
79+
understand how the text is used and ensure that the translation is appropriate
80+
for the situation.
81+
82+
Choose a project that you think is already used in your language area, or a project
83+
that you are going to work on and want to give your customers/users access to in
84+
their own language. Alternatively, you can choose one of the projects that in
85+
TYPO3's Extension Repository have the most likes and are thus also the most popular.
86+
Popular projects typically have a lot of users, so your contribution will have a
87+
big impact.
88+
89+
If you want to get started with the TYPO3 CMS project, there are typically many
90+
words (>60.000 and counting) and strings that need to be translated. Here, it is
91+
especially important to have a good plan from the start: A good start is the
92+
Glossary with all the terms. Continue with files in the main branch – then you
93+
know that you will hit the most users. We still hold previous (E)LTS versions
94+
in but unless you have massive energy, leave these files.
95+
96+
And follow the recommendations above, work in a structured way through files and
97+
projects. It can be an advantage to set intermediate goals along the way, so that
98+
you stay motivated even if the project is big.
99+
100+
To wrap it up:
101+
102+
* Start with a small project with a few words and strings to make the work manageable.
103+
* Choose a project that motivates you to keep your spirits up.
104+
* Feel free to translate one file at a time to get a better understanding of the context.
105+
* Choose projects that are already in use in your language area or that you will be working on yourself.
106+
* Consider tackling popular projects – your contribution will have a greater impact.
107+
* If you are translating TYPO3 CMS, start with the Glossary if it's not
108+
already translated, and continue in the main branch to reach the most users.
109+
* Work in a structured way and preferably set sub-goals to maintain motivation in larger projects.
110+
111+
.. _crowdin-bestpractice-use-ext-crowdin:
112+
113+
Use EXT:Crowdin
114+
---------------
115+
116+
There is an extension that you can use with great advantage for translations of
117+
both frontend and backend. EXT:Crowdin integrates the in-context editing of Crowdin
118+
into TYPO3, making it quick and easy to add translations of XLF files used in the
119+
backend. With this extension, you can get a more streamlined workflow, where you
120+
don't have to switch between multiple programs or platforms. This allows you to
121+
work more efficiently and easily keep track of which files have been translated
122+
and which ones are missing. And most important: the extension gives you context
123+
to the string, you currently translate, because you can see right away where
124+
it is used in TYPO3.
125+
126+
You find the Extension here: `Extension Crowdin | TER`_
127+
128+
.. _Extension Crowdin | TER: https://extensions.typo3.org/extension/crowdin
129+
130+
.. _crowdin-bestpractice-setup-translating:
131+
132+
Crowdin setup when translating
133+
------------------------------
134+
135+
The prerequisite for getting started is that you are either a translator or proofreader
136+
in Crowdin, and that you are logged in with your user profile. When you open Crowdin
137+
and choose to start translating a project, the project's Dashboard opens, and you
138+
get a list of all the languages that are available for translation in the project.
139+
Select your language and the files that can be translated will appear. Here you
140+
have the option to start translating all files (Translate All) or start with a
141+
single file (the three dots ···), as described in the introductory considerations above.
142+
143+
Now you're up and running! We recommend that you stay with the default Editor
144+
View "Comfortable". Here you have an overview of several parts of your work at the same time. You can
145+
see the source text, suggestions from Translation Memory, comments from other
146+
translators, and the status of each string. Editor View also offers a range of
147+
features that make it easier to work with larger projects, such as filtering strings
148+
by status, search function, and accessing glossary and TM directly from the editor.
149+
150+
For a detailed presentation of the translation view, see Crowdin Docs. Here you
151+
will also find guides to the different editor options and tips on how to get the
152+
most out of the tool.
153+
154+
You find the Crowdin Docs here: `Crowdin Docs`_
155+
156+
.. _Crowdin Docs: https://support.crowdin.com/
157+
158+
.. _crowdin-bestpractice-glossary:
159+
160+
Working with Glossary
161+
---------------------
162+
163+
A Glossary is used to establish a terminology and frequently used terms within a
164+
project. In TYPO3 we have a common Glossary – The TYPO3 CMS Great Glossary. Here
165+
we have selected several terms that are often used in TYPO3 and that must be
166+
written consistently in all projects. It can be terms like 'TypoScript,' 'TsConfig,'
167+
'Cache,' and so on. A well-maintained glossary helps to ensure that terminology is
168+
consistent across translations, making it easier for both new and experienced users
169+
to navigate the system.
170+
171+
Working with Glossary is work-in-progress, and you are welcome to maintain it in
172+
your preferred language. If you come across new terms or see opportunities to
173+
improve definitions, you can contribute directly in Crowdin. This strengthens
174+
collaboration and makes it easier for future translators to deliver high quality.
175+
176+
You can read more about creating and using Glossary on Crowdin Docs: `Glossary | Crowdin Docs`_
177+
178+
.. _Glossary | Crowdin Docs: https://support.crowdin.com/glossary/
179+
180+
.. _crowdin-bestpractice-tm:
181+
182+
Translation Memory (TM)
183+
-----------------------
184+
185+
Translation Memory(TM) is a central part of a translation tool like Crowdin. TM
186+
consists of a database that constantly stores words and phrases as you go and
187+
offers previous translations as you work. This saves time and ensures a consistent
188+
translation style, especially on large projects where many strings recur across files.
189+
190+
In TYPO3 we have a common TM – The TYPO3 CMS Great TM. Here, a large library is
191+
slowly and patiently built up, which helps in the daily work. TM will constantly
192+
suggest strings from TM that match either 100% or close by. In this way, you can
193+
quickly move on in the work and avoid doing duplicate work. Consider using existing
194+
translated strings instead of adding new ones, as this ensures consistency across
195+
the project.
196+
197+
Only translated texts and words that have been approved by a proofreader are stored
198+
in TM. It means a lot for the quality of TM that we do not mix up too many 'almost
199+
identical' words and sentences in the same TM. A good TM makes it easier to achieve
200+
consistency in translations, and you don't have to reinvent the wheel repeatedly.
201+
202+
Read more about Translation Memory on Crowdin Docs: `Translation Memory | Crowdin Docs`_
203+
204+
.. _Translation Memory | Crowdin Docs: https://support.crowdin.com/translation-memory/
205+
206+
.. _crowdin-bestpractice-shortcuts:
207+
208+
Shortcuts and efficiency
209+
------------------------
210+
211+
In Editor View, you can access a wide range of shortcuts via the keyboard. You
212+
can view the list by clicking on the small keyboard icon in the top right corner.
213+
Shortcuts can save you a lot of clicks and make it easier to navigate, especially
214+
when you're working on large projects. Check out the list of shortcuts and try it
215+
out – you'll quickly discover which ones best suit your working style.
216+
217+
.. _crowdin-bestpractice-communication:
218+
219+
Communication and collaboration
220+
-------------------------------
221+
222+
Write, comment and suggest! In TYPO3, we primarily have two channels in Slack:
223+
TYPO3 translations for questions and problems about working with translations,
224+
and TYPO3 localization team for driving the process around Crowdin, TYPO3 and
225+
localization. It is important to use these channels actively, as collaboration
226+
and knowledge sharing often lead to better and more accurate translations. You
227+
can ask questions, share experiences, and help others if you encounter challenges.
228+
229+
Go to TYPO3 Slack:
230+
231+
* Sign Up for a `TYPO3 Slack Account`
232+
* Channel questions and problems working with translations:
233+
`typo3-translations | Slack`_
234+
* Channel for the localization team: `typo3-localization-team | Slack`_
235+
236+
.. _TYPO3 Slack Account: https://docs.typo3.org/m/typo3/guide-step-by-step/main/en-us/10GettingStarted/05MeetTheCommunity/SignUpForATypo3SlackAccount.html
237+
.. _typo3-translations | Slack: https://typo3.slack.com/archives/C032FRT0W
238+
.. _typo3-localization-team | Slack: https://typo3.slack.com/archives/CR75200FL
239+
240+
.. _crowdin-bestpractice-stuck:
241+
242+
If you get stuck
243+
----------------
244+
245+
Sometimes a text can be difficult to translate. Consider leaving it for later.
246+
Once you've worked through the rest of the translation, you'll often get a better
247+
picture of the overall text, and it'll be easier to come back and translate the
248+
remaining sentences and words. If in doubt, you can also ask in the Slack channels
249+
or seek advice from more experienced translators.
250+
251+
.. _crowdin-bestpractice-stick-lyrics:
252+
253+
Stick to the lyrics
254+
-------------------
255+
256+
Do not translate texts within curly brackets (for example, {@viewPortLabel}). These
257+
are placeholders that are filled in by TYPO3 when the text is displayed. Translating
258+
them can lead to system errors or features not working as expected. It is therefore
259+
important to keep an eye on these and leave them unchanged.
260+
261+
.. _crowdin-bestpractice-100-percent:
262+
263+
Don't trust 100% on 100%
264+
------------------------
265+
266+
Crowdin shows one percent for each language, but it's a bit misleading. Old versions
267+
do not have to be completely translated, so a language can easily be finished, even if
268+
the counter may only say 50%. And even if it says "100% finished", it doesn't mean
269+
that everything just plays – it's always a good idea to just read through the text
270+
and check if it sounds proper and natural in your language. Quality is not
271+
only a question of quantity, but also of whether the text is understandable and accurate.
272+
273+
Inside each version folder there is also a counter, but it only tells you how many
274+
words are missing in that version. This can mean that 50% is either half of 1,000
275+
words or half of 5,000 words – so it is not to be counted on. If we correct just
276+
one word in a sentence, Crowdin counts the entire sentence as changed. Luckily,
277+
it shows the translation from the old version, so you can copy and correct just
278+
that one word – it's fast and saves time.
279+
280+
.. _crowdin-bestpractice-final:
281+
282+
Final thoughts
283+
--------------
284+
285+
To ensure the quality of the translations, it may be a good idea to do an extra
286+
review where you check for consistency, spelling mistakes and whether the texts
287+
sound natural in in your language. Put yourself in the position of an unexperienced
288+
user of TYPO3. Would you understand the translation?
289+
290+
Feel free to share your experiences and best tips with the community – it empowers
291+
everyone, and together we can make TYPO3 even better and more accessible to users
292+
all over the world.
293+
294+
.. _crowdin-bestpractice-further-readings:
295+
296+
Further readings
297+
----------------
298+
299+
Get inspired by Martin Pribyl's article about how he did a full translation and
300+
proofreading of TYPO3 CMS into Czech language: `Bringing Czech to TYPO3 - My Translation Journey`_
301+
302+
.. _Bringing Czech to TYPO3 - My translation Journey: https://typo3.org/article/bringing-czech-to-typo3-my-translation-journey
303+

0 commit comments

Comments
 (0)