Re: Weblate Translation Tips

On Sun, Aug 22, 2021 at 8:16 PM Danilo G. Baio <dbaio@freebsd.org> wrote:
>
>
>
> On Sun, Aug 22, 2021, at 11:33, Fernando Apesteguía wrote:
> > On Sun, Aug 8, 2021 at 6:47 PM Danilo G. Baio <dbaio@freebsd.org> wrote:
> > >
> > >
> > >
> > > On Sun, Aug 8, 2021, at 13:41, Fernando Apesteguía wrote:
> > > > El dom., 8 ago. 2021 18:36, Danilo G. Baio <dbaio@freebsd.org> escribió:
> > > >
> > > > >
> > > > >
> > > > > On Sun, Aug 8, 2021, at 11:09, Fernando Apesteguía wrote:
> > > > > > On Sat, Aug 7, 2021 at 9:24 PM Danilo G. Baio <dbaio@freebsd.org> wrote:
> > > > > > >
> > > > > > > Hi.
> > > > > > >
> > > > > > > As you may know, we are still adjusting the translation workflow of the
> > > > > > > FreeBSD Documentation Project through Weblate, there are some pending
> > > > > > > items [1], but everyone can [re-]start translating.
> > > > > > >
> > > > > > > I've just added this wiki page [2] describing how to translate/build
> > > > > > > each document (for now, there are only three).
> > > > > > >
> > > > > > > The 'Article / Contributors to FreeBSD' [3] is a good example that
> > > > > every
> > > > > > > language should follow to keep all contributor's names updated.
> > > > > > >
> > > > > > > If you have any questions, please let us know.
> > > > > >
> > > > > > Hi Danilo,
> > > > > >
> > > > > > Thanks for this. It is very helpful!
> > > > > >
> > > > > > Some questions. In the example on how to update the "Contributors to
> > > > > > FreeBSD" article, it is said: "Just necessary translate index and
> > > > > > contrib-develinmemoriam."
> > > > > > In es/ we do not have any contributors/ directory. Not a big deal, we
> > > > > > can create a new one based on another language. But here is the
> > > > > > question. If we compare the directories pt_BR/ and en/:
> > > > > >
> > > > > >  ls ../../../en/articles/contributors/
> > > > > > _index.adoc                   contrib-386bsd.adoc
> > > > > > contrib-additional.adoc       contrib-committers.adoc
> > > > > > contrib-corealumni.adoc       contrib-develalumni.adoc
> > > > > > contrib-develinmemoriam.adoc  contrib-portmgralumni.adoc
> > > > > >
> > > > > > $ ls ../../../pt-br/articles/contributors/
> > > > > > _index.adoc                   _index.po
> > > > > > contrib-develinmemoriam.adoc  contrib-develinmemoriam.po
> > > > > >
> > > > > > Should I base the new "Contributors" article in the English version or
> > > > > > another one?
> > > > > >
> > > > > > Thanks!
> > > > >
> > > > >
> > > > > Hi Fernando.
> > > > >
> > > > > In this case, you can follow pt-br; the missing files are
> > > > > referenced/included
> > > > > directly from the English directory.
> > > > >
> > > > > include::content/en/articles/contributors/contrib-committers.adoc[]
> > > > > include::content/en/articles/contributors/contrib-corealumni.adoc[]
> > > > > include::content/en/articles/contributors/contrib-develalumni.adoc[]
> > > > > include::content/en/articles/contributors/contrib-portmgralumni.adoc[]
> > > > > include::{include-path}contrib-develinmemoriam.adoc[]
> > > > > include::content/en/articles/contributors/contrib-additional.adoc[]
> > > > > include::content/en/articles/contributors/contrib-386bsd.adoc[]
> > > > >
> > > > > You have to change this manually after translating with
> > > > > ./tools/translate.sh.
> > > > >
> > > >
> > > > Oops, yes. It was there in the wiki!
> > > >
> > > > Thanks for the clarification!
> > >
> > >
> > > Ah, don't worry. If you note something that is not there, let us know. or just update the wiki page  :)
> >
> > At the risk of exhausting your patience... :-)
> >
>
> Hi Fernando.
> Not at all. This is good to improve instructions.
> You and everyone can ask anything. It's good to see that more people are translating FreeBSD documents.
>
>
> > I tried to follow the guide, and got stuck running the translate.sh script:
> >
> > $ ./tools/translate.sh documentation es
> > .....
> > documentation/content/es/articles/contributors/_index.po
> > Your input po file
> > documentation/content/es/articles/contributors/_index.po seems
> > outdated (The amount of entries differ between files: 73 is not 74
> > ). Please consider running po4a-updatepo to refresh it.
> > .....
> > documentation/content/es/articles/contributors/contrib-develinmemoriam.po
> >
>
>
> You can use this variable/env so po4a-translate will ignore the translation percentage:
>
> $ KEEP_ENV=0 ./tools/translate.sh documentation es
> .....
> documentation/content/es/articles/contributors/_index.po
> Your input po file documentation/content/es/articles/contributors/_index.po seems outdated (The amount of entries differ between files: 73 is not 74
> ). Please consider running po4a-updatepo to refresh it.
> .....
> documentation/content/es/articles/contributors/contrib-develinmemoriam.po
>
>
> $ find documentation/content/es/articles/contributors/
>   documentation/content/es/articles/contributors
>   documentation/content/es/articles/contributors/contrib-develinmemoriam.adoc
>   documentation/content/es/articles/contributors/_index.po
>   documentation/content/es/articles/contributors/_index.adoc
>   documentation/content/es/articles/contributors/contrib-develinmemoriam.po
>
>
> I'll update the wiki instructions later with the KEEP_ENV=0.
>
>
> > I did the copy as the guide suggested in very updated freebsd-doc and
> > freebsd-doc-translate repos and nevertheless repeated the process, but
> > po4a-translate always complains about the number of entries mismatch.
> >
> > As a side note, I finished the Spanish translation of
> > articles/contributors in Weblate. After a few minutes, I pulled the
> > changes in freebsd-doc-translate. If I continue translating with
> > weblate and pull the changes in my local copy of
> > freebsd-doc-translate, can I use that as base to do the copy to
> > freebsd-doc? Of course I need to translate the other documents
> > (contrib-*.po).
> >
> > Cheers
>
> Yes, you can use it.
> Last update on Weblate is from 2021-07-25 [1].
> There was only one change on articles/contributors [1] since that.  It's a single '+', just check/include that.
>
>
> 1 - https://cgit.freebsd.org/doc/commit/?id=d369054ed343acb84f1091d5a676c1039ed62d76
> 2 - https://cgit.freebsd.org/doc/commit/documentation/content/en/articles/contributors/_index.adoc?id=a5d0b55b2fc7761041a0bb115eefdb10ff0f8af0

Thank you very much! It's been really clarifying.

I see in contributors/_index.adoc we are including documents from en/
e.g. the list of additional contributors. These files are made purely
of names and email addresses that do not need translation. In Weblate,
these appear as untranslated documents. With this workflow, I
understand we will never want to translate those files, right?
Including them, guarantees that the list of contributors, additional
contributors, etc is always in sync with the master (aka English)
version.

Should we somehow disable those documents in Weblate? I see the
Manage->Removal option, but I was thinking more in terms of "locking"
the document and showing the translator a message about how those
files are included. I didn't see anything like that on Weblate.

Cheers.
>
> Regards.
> --
> Danilo G. Baio