Re: Documentation/translations: Italian

[Federico Vaga]

On Tuesday, 22 May 2018 01:00:35 CEST Jonathan Corbet wrote:
> On Mon, 21 May 2018 22:54:18 +0200
> 
> Federico Vaga  wrote:
> > I'm writing you because I would like to start an effort to
> > translate the Documentation in Italian. I would like also to
> > express the idea of providing guide lines for translations.
> 
> Mi sembra un'ottima idea! :)

Siamo sulla stessa lunghezza d'onda :)
 
> > I know that there are already translations for Asian languages but
> > I am not able to find the history of them. I do not know if
> > translations in European languages are going to be accepted
> > (perhaps there is the assumption that everyone knows English in
> > the European continent and it is a waste of energy to do
> > translations[?]). For example, even if French and Germans are
> > quite active there are not translations yet in their language: is
> > there a particular reason or simply nobody did it?
> 
> Nobody has done it.  There certainly is no policy against
> translations to any specific language - that would be hard to
> justify, to say the least.
> 
> OK, I might draw the line at Klingon.  But the discussion of error
> handling in Klingon could actually be a lot of fun.
> 
> I'm happy to accept new translations of stuff in the documentation
> directory.  In general, I've had two concerns about translations:
> they are generally impossible for me to review, and there needs to
> be somebody committed to keeping the translations current as the
> documentation changes.  For Italian, the first problem doesn't
> exist, but the second is always there. What are your intentions for
> maintaining the translations in the long term?

I can maintain the Italian translation. 
 
> > If you agree with the need to support different translations, I
> > would like to do the Italian one. But first I would like to open
> > a little discussion about translations  "how to write
> > translations"; this discussion should produce a document (in
> > English) with guide lines for translator (e.g. Documentation/
> > translation/howto.rst): what to translate first, what to NOT
> > translate, how to structure it.
> > Once this is defined I will start the Italian translation (I
> > already have some documents translated).
> 
> This can be a fine plan, assuming we're convinced that the
> guidelines document is really needed.  I guess I'm not yet
> convinced of that.  But you might also consider gaining some
> experience in writing, merging, and maintaining a translation
> before trying to lay down rules for everybody else.  In other
> words, I think you might want to do things in the opposite order.

You are right, probably I was over-engineering this thing :)

> 
> > How to do translations (IMHO)
> > -
> > Here my personal guide lines for translations
> > 
> > - Translate only sphinx-ready documents, do not translate
> > documents which are not yet sphinx. We should avoid useless
> > double work; at some point, I guess, everything will be sphinx.
> 
> I wouldn't insist on that.  But a better idea in any case would be:
> if a document you want to translate isn't yet in RST, just do the
> conversion. The amount of work required is usually quite small.

ok

> > - Include in all documents a disclaimer saying that English is the
> > main reference (use sphinx directive 'include' to include it).
> > - Include in all documents a reference to the English version. So
> > it will be easy jump to the original document.
> 
> Remember that the docs need to be readable *without* Sphinx
> processing. Better to just name the source document in a quick line
> at the top, IMO.

ok

> > - Translate in order: non-technical documents (they are stable,
> > useful for a wider group of people (developers and managers):
> > process/, doc-guide/ ), technical documents about key concepts
> > (they are stable, and important for new-comers), subsystems (the
> > big picture is stable, typically they do not describe all little
> > details that may change), and then other documents
> If you want to work in that order, that is more than fine.  Others
> have agreed - the process docs tend to get translated first.  But
> if somebody else wants to start elsewhere, I wouldn't try to tell
> them not to.
> 
> Anyway, thanks for wanting to help improve the documentation!  If
> you have some of this work already done, you might want to consider
> going ahead and posting some patches.

I will review them and push something in the next days

-- 
Federico Vaga
http://www.federicovaga.it/


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Documentation/translations: Italian

[Jonathan Corbet]

On Mon, 21 May 2018 22:54:18 +0200
Federico Vaga  wrote:

> I'm writing you because I would like to start an effort to translate the 
> Documentation in Italian. I would like also to express the idea of providing 
> guide lines for translations.

Mi sembra un'ottima idea! :)

> I know that there are already translations for Asian languages but I am not 
> able to find the history of them. I do not know if translations in European 
> languages are going to be accepted (perhaps there is the assumption that 
> everyone knows English in the European continent and it is a waste of energy 
> to do translations[?]). For example, even if French and Germans are quite 
> active there are not translations yet in their language: is there a 
> particular 
> reason or simply nobody did it?

Nobody has done it.  There certainly is no policy against translations to
any specific language - that would be hard to justify, to say the least.

OK, I might draw the line at Klingon.  But the discussion of error handling
in Klingon could actually be a lot of fun.

I'm happy to accept new translations of stuff in the documentation
directory.  In general, I've had two concerns about translations: they are
generally impossible for me to review, and there needs to be somebody
committed to keeping the translations current as the documentation
changes.  For Italian, the first problem doesn't exist, but the second is
always there. What are your intentions for maintaining the translations in
the long term?

> If you agree with the need to support different translations, I would like to 
> do the Italian one. But first I would like to open a little discussion about 
> translations  "how to write translations"; this discussion should produce a 
> document (in English) with guide lines for translator (e.g. Documentation/
> translation/howto.rst): what to translate first, what to NOT translate, how 
> to 
> structure it.
> Once this is defined I will start the Italian translation (I already have 
> some 
> documents translated).

This can be a fine plan, assuming we're convinced that the guidelines
document is really needed.  I guess I'm not yet convinced of that.  But you
might also consider gaining some experience in writing, merging, and
maintaining a translation before trying to lay down rules for everybody
else.  In other words, I think you might want to do things in the opposite
order.

> How to do translations (IMHO)
> -
> Here my personal guide lines for translations
> 
> - Translate only sphinx-ready documents, do not translate documents which are 
> not yet sphinx. We should avoid useless double work; at some point, I guess, 
> everything will be sphinx.

I wouldn't insist on that.  But a better idea in any case would be: if a
document you want to translate isn't yet in RST, just do the conversion.
The amount of work required is usually quite small.

> - Include in all documents a disclaimer saying that English is the main 
> reference (use sphinx directive 'include' to include it).
> - Include in all documents a reference to the English version. So it will be 
> easy jump to the original document.

Remember that the docs need to be readable *without* Sphinx processing.
Better to just name the source document in a quick line at the top, IMO.

> - Translate in order: non-technical documents (they are stable, useful for a 
> wider group of people (developers and managers): process/, doc-guide/ ), 
> technical documents about key concepts (they are stable, and important for 
> new-comers), subsystems (the big picture is stable, typically they do not 
> describe all little details that may change), and then other documents

If you want to work in that order, that is more than fine.  Others have
agreed - the process docs tend to get translated first.  But if somebody
else wants to start elsewhere, I wouldn't try to tell them not to.

Anyway, thanks for wanting to help improve the documentation!  If you have
some of this work already done, you might want to consider going ahead and
posting some patches.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Documentation/translations: Italian

[Federico Vaga]

Hello,

I'm writing you because I would like to start an effort to translate the 
Documentation in Italian. I would like also to express the idea of providing 
guide lines for translations.

A looked a bit in the archive but I did not find anything about these two 
topics (Italian translation, guide lines for translations).

I know that there are already translations for Asian languages but I am not 
able to find the history of them. I do not know if translations in European 
languages are going to be accepted (perhaps there is the assumption that 
everyone knows English in the European continent and it is a waste of energy 
to do translations[?]). For example, even if French and Germans are quite 
active there are not translations yet in their language: is there a particular 
reason or simply nobody did it?

Why
===
There is nothing better for understanding than our own mother tongue, and 
reading Documentation is one of those activities where it is important to 
understand its message rather than learning a different language (there are 
dedicated books and courses for that). This is especially true for young 
developers and new-comers who are really focused on understanding Linux and a 
different language can be an obstacle sometimes. I personally had a couple of 
experiences where I pointed people to the documentation and I had to explain 
English rather than Linux. Very competent people but they were not used to use 
English every day.

I put myself in this list of people who prefer the mother tongue language when 
it is time to really understand something. I work for an international 
organization in a country that is not mine with people coming from all around 
the European continent and our common tongue is bad-English with all its 
dialects and accents: true-English (with its own dialects), spaghetti-English, 
kartoffel-English, paella-English, formage-English and more. Misunderstanding 
is not rare, and sometimes express ourselves takes more time than needed. This 
is another reason why I believe that for understanding purposes is good to 
read in our own mother tongue.

Plan

If you agree with the need to support different translations, I would like to 
do the Italian one. But first I would like to open a little discussion about 
translations  "how to write translations"; this discussion should produce a 
document (in English) with guide lines for translator (e.g. Documentation/
translation/howto.rst): what to translate first, what to NOT translate, how to 
structure it.
Once this is defined I will start the Italian translation (I already have some 
documents translated).

How to do translations (IMHO)
-
Here my personal guide lines for translations

- Translate only sphinx-ready documents, do not translate documents which are 
not yet sphinx. We should avoid useless double work; at some point, I guess, 
everything will be sphinx.
- Include in all documents a disclaimer saying that English is the main 
reference (use sphinx directive 'include' to include it).
- Include in all documents a reference to the English version. So it will be 
easy jump to the original document.
- Translate in order: non-technical documents (they are stable, useful for a 
wider group of people (developers and managers): process/, doc-guide/ ), 
technical documents about key concepts (they are stable, and important for 
new-comers), subsystems (the big picture is stable, typically they do not 
describe all little details that may change), and then other documents
- avoid scattered translations: try to finish one "topic" before translating 
something else

Probably there is much more, that's why I would like to have a little 
discussion about it.


Thanks for reading everything :)

-- 
Federico Vaga
http://www.federicovaga.it/


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html