Possible help files rename?

l10n
#1

Hi Regina, all,

Regina Henschel píše v St 18. 11. 2015 v 21:32 +0100:

most of the file names are build of numbers and it
is hard to identify the relevant file.

That's indeed true :slight_smile:

I wonder - would a large scale rename to something more readable (like
eg. filename constructed from the <title> tag) be more appreciated by
people editing help?

L10n people - any blockers from the tooling point of view that hinder
that, please? Would it mean that the .po files have to be renamed too,
and if yes, it is possible to do that somehow automatically?

All the best,
Kendy

#2

.po files are named after directories, not after files. In .po files
file names are there in #: comments and in msgctx fields. It is
possible to automatically replace file names in git and in Pootle, but
this can cause disruption for translators who work offline, and
translation memories have to be regenerated.

Regards,
Andras

#3

Please, once more, do not do any "l'art pour l'art"-istic changes that
might cause any kind of trouble to localizers.

There are many more things to invest time and will in first - to write
missing help content, to edit the help content, to make
wiki-served-help fully localizable, to have manuals (getting started
guides) up-to-date etc.

Most localizers localize from Pootle and I am sure that po files there
could be given additional description what part of UI or help they
cover, if really someone feels lost.

Lp, m.

#4

Hi Martin,

Martin Srebotnjak píše v Út 24. 11. 2015 v 15:54 +0100:

Please, once more, do not do any "l'art pour l'art"-istic changes that
might cause any kind of trouble to localizers.

There are many more things to invest time and will in first - to write
missing help content, to edit the help content, to make
wiki-served-help fully localizable, to have manuals (getting started
guides) up-to-date etc.

Exactly! And to be able to do so, we need to lower the entry barrier,
so that more people can write the help content, update the manuals, etc.

We have just seen a guy interested in editing help, and this was one of
his struggles there - that he just couldn't find the help file he needs
to edit. Asking him to grep all the main0123.xhp files (and alike) is
just as nice as telling him "go away, we don't want you" :frowning:

That's why I am interested to learn what are the technical & workflow
difficulties to make the barrier lower, and what is the impact on the
localizers.

We need to do changes to be more open for documentation contributions,
that's something we just cannot avoid, otherwise our help will be
completely outdated soon. So I'm asking if (and what) we can do in a
way that causes no or only minimal trouble.

Most localizers localize from Pootle and I am sure that po files there
could be given additional description what part of UI or help they
cover, if really someone feels lost.

"Most localizers localize from Pootle" together with:

> It is
> possible to automatically replace file names in git and in Pootle, but
> this can cause disruption for translators who work offline, and
> translation memories have to be regenerated.

actually makes me think that only a small fraction of translators would
be actually disrupted, because for those using Pootle, it would be
transparent. So did I misunderstand?

Thank you for your help!

All the best,
Kendy

#5

Probably Slovenian would be actually disrupted, and other "offline"
localization teams, I do not have a list.

Lp, m.

#6

Þann þri 24.nóv 2015 15:35, skrifaði Martin Srebotnjak:

actually makes me think that only a small fraction of translators would
be actually disrupted, because for those using Pootle, it would be
transparent. So did I misunderstand?

Probably Slovenian would be actually disrupted, and other "offline"
localization teams, I do not have a list.

Lp, m.

Martin, I prefer translating offline, and honestly I fail to see too much of a problem if the helpfiles were renamed from 01.po, 02.po to something more meaningful. And if comments and msgctx fields are to be changed - why not...

(I do regenerate my translation memories regularly)

Sveinn í Felli

#7

Sveinn,

I am not sure we are talking about the same thing or that I understand
this correctly.

They change the names of the help files (i.e. calc/01.po is now
calcsfirsthelpfilewithhelpaboutfunctions.po). For the migration
process they become new po files.

The pomigrate2 script takes the translation memory, but it was
generated from the old files (like the old calc/01.po file) with
different msgctx and comment fields etc. So even if all strings in the
renamed file are actually the same as in 01.po , they will become
fuzzy strings, right?

So for calc/01.po that is like 8000 strings, fuzzy strings. And since
we translators will not know if there is at least one changed or
updated string in there, we will have to go manually through all those
8000 strings, reading and checking and ultimately 8000 times clicking
it is not a fuzzy but an ok translation.

Well, if that is done in all help files, it means 26000 reviewed
strings with 26000 clicks that these strings are just fine.

Am I wrong?

100 localization teams doing those 26000 clicks would mean like
2.600.000 reviewed strings ...

I hope I am wrong.

Lp, m.

#8

Hi Martin,

Martin Srebotnjak píše v Út 24. 11. 2015 v 21:57 +0100:

I am not sure we are talking about the same thing or that I understand
this correctly.

They change the names of the help files (i.e. calc/01.po is now
calcsfirsthelpfilewithhelpaboutfunctions.po). For the migration
process they become new po files.

Nope, did not intend to change the directories, so I was happy to hear
that the .po files are named by the directories.

So as a result, calc/01.po will still stay calc/01.po; only the
filenames inside would change - eg. in:

#. ZxQeC
#: main0000.xhp
msgctxt ""
"main0000.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

only the 'main0000.xhp' would change to '0000-Welcome-to-the-officename-Calc-Help.xhp' resulting in

#. ZxQeC
#: 0000-Welcome-to-the-officename-Calc-Help.xhp
msgctxt ""
"0000-Welcome-to-the-officename-Calc-Help.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

Sorry for not being precise in my question previously, but first I
needed to understand how exactly the .xhp's map to the .po files :slight_smile:

Does this work / is this change possible without much hassle?

Thank you again,
Kendy

#9

Hi Kendy, all,

Hi Martin,

Martin Srebotnjak píše v Út 24. 11. 2015 v 21:57 +0100:

I am not sure we are talking about the same thing or that I understand
this correctly.

They change the names of the help files (i.e. calc/01.po is now
calcsfirsthelpfilewithhelpaboutfunctions.po). For the migration
process they become new po files.

Nope, did not intend to change the directories, so I was happy to hear
that the .po files are named by the directories.

So as a result, calc/01.po will still stay calc/01.po; only the
filenames inside would change - eg. in:

#. ZxQeC
#: main0000.xhp
msgctxt ""
"main0000.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

only the 'main0000.xhp' would change to '0000-Welcome-to-the-officename-Calc-Help.xhp' resulting in

#. ZxQeC
#: 0000-Welcome-to-the-officename-Calc-Help.xhp
msgctxt ""
"0000-Welcome-to-the-officename-Calc-Help.xhp\n"
"tit\n"
"help.text"
msgid "Welcome to the $[officename] Calc Help"
msgstr "Vítejte v nápovědě k $[officename] Calc"

Sorry for not being precise in my question previously, but first I
needed to understand how exactly the .xhp's map to the .po files :slight_smile:

Does this work / is this change possible without much hassle?

this result on changing the msgctxt, so all the files will be changed.
We should also check with Dwayne if it's not used in some
indexation/search processes on Pootle.

Why do we want to change if the main_transform.xsl file is working now
correctly and allow an easy search? I agree that the file name remains
not easy to understand, but if a tool solve that, where is the issue
then? It seems really less invasive than changing the name and a low
curve to learn how to access a given file for new comers.

There is another file we were using to search the help, it's
allfiles.tree, that could be used to list all files in a tree form. I
didn't test if it still work or not, I think I sent both files to you
Kendy, but I'll try to find the time to test it today.

Cheers
Sophie

#10

Hi Sophie, *.

Hi Kendy, all,

#. ZxQeC
#: main0000.xhp
msgctxt ""
"main0000.xhp\n"
[…changed to…]
#. ZxQeC
#: 0000-Welcome-to-the-officename-Calc-Help.xhp
msgctxt ""
"0000-Welcome-to-the-officename-Calc-Help.xhp\n"

Sorry for not being precise in my question previously, but first I
needed to understand how exactly the .xhp's map to the .po files :slight_smile:

Does this work / is this change possible without much hassle?

this result on changing the msgctxt, so all the files will be changed.

But this is a change that can be easily scripted, have a map oldname →
newname and then run a script over the files replacing the filename.
Much easier to do than the help-ID changes in the past, since you
don't need to manually account for "shifts" in the changes.

We should also check with Dwayne if it's not used in some
indexation/search processes on Pootle.

indexes can be recreated, so no hurdle in itself..

ciao
Christian

#11

Hi Sophie,

Sophie píše v St 25. 11. 2015 v 11:52 +0100:

Why do we want to change if the main_transform.xsl file is working now
correctly and allow an easy search? I agree that the file name remains
not easy to understand, but if a tool solve that, where is the issue
then?

to pile workaround on top of each other to achieve something that would
be possible by fixing the initial problem in the first place.

Additional file means additional complexity, and additional thing to
explain to the newcomers - so that's why I am interested in fixing this
by the rename.

But again - for the moment I'm only researching what are the
consequences & if this is acceptable by the l10n community :slight_smile:

All the best,
Kendy