On Thu, Apr 9, 2015 at 8:34 AM, Ying Chun Guo <guoyingc@cn.ibm.com> wrote:

I did an assessment of the string changes affected by this action,
in order to evaluate the extra workload for translators to translate the new versions,
assuming the old version of DocBook pot files are 100% completed translation.

I download the English source files of these following resources from Transifex:
openstack-manuals-i18n.user-guides ( RST format )
openstack-manuals-i18n.user-guide ( DocBook format )
openstack-manuals-i18n.user-guide-admin ( DocBook format )

openstack-manuals-i18n.user-guides is the new RST document, which is a combination of openstack-manuals-i18n.user-guide
and openstack-manuals-i18n.user-guide-admin, including new contents and changes.

I found three types of changes:
1. all strings including XML markups are changed, XML markups being removed, replacing with RST format characters.
e.g.
"To perform a hard reboot, pass the <parameter>--hard</parameter> parameter, "
"as follows:"
is changed to:
"To perform a hard reboot, pass the ``--hard`` parameter, as follows::"

2. some strings are added ** and ** as prefix and suffix.
e.g.
"Removal or addition of segment objects"
is changed to
"**Removal or addition of segment objects**"

3. all strings ending with ":" are changed, ending with "::" instead.
e.g.
"To perform an instance reboot into rescue mode, run the following command:"
is changed to
"To perform an instance reboot into rescue mode, run the following command::"

Then I calculated the numbers of strings.

openstack-manuals-i18n.user-guide (old docbook ) has 2005 strings, including
779 (39%) strings exactly moved to new RST pot,
1226 (61%) strings which are either changed (mostly) or removed.

openstack-manuals-i18n.user-guide-admin (old docbook ) has 653 strings, including
277 strings (42%) exactly moved to RST pot,
376 strings (58%) which are either changed (mostly) or removed.

openstack-manuals-i18n.user-guides ( new RST ) has 2892 strings, including 779 (27%) strings exactly
matched strings in user-guide, 277 (10%) strings exactly matched strings in user-guide-admin,
and 1861 (64%) strings matched nothing.

That means, if translators have 100% completed openstack-manuals-i18n.user-guide and openstack-manuals-i18n.user-guide-admin translation,
the translation completion rate for the new RST file is 36%.

After a deep dive of the new RST pot file, there are 196 strings ending with double colon and 70 strings with prefix ** and suffix **.
If we use scripts to change those strings and make them exactly match, the auto completion rate could be improved from 36% to 45%.

As to the XML markup changes, they are quite difficult to auto match.
openstack-manuals-i18n.user-guide has 25% strings including XML markups, and
openstack-manuals-i18n.user-guide-admin has 33% strings including XML markups.
We might have to change manually.

But, no team has big progress with user-guide-admin and user-guide translation, except Japanese team.
So I think, the tolerance to manually change the translations are acceptable.

Thanks for this thorough analysis. This information is extremely helpful.
 

BTW, my analysis has nothing with the translators feeling to RST markups.
In my mind, while I translate DocBook, I have to copy XML markups.
The same happen to me if I translate RST books. I have to copy RST markups.
I just need to understand which words are RST markups and should not be translated.
Maybe doc team could give us a list of these special RST markups for us to reference.


Agreed. Andreas has completely gone through our conventions and indicated the equivalent markups in DocBook and RST.

https://wiki.openstack.org/wiki/Documentation/Markup_conventions

For example, <filename>nova.conf</filename> in DocBook becomes :file:`nova.conf` in RST, as shown in this section:
https://wiki.openstack.org/wiki/Documentation/Markup_conventions#File_name_or_path

Do you have a list of "ignored" markup already? We could take a look and see if a mapping is fairly straightforward based on what we have.

Thanks,
Anne



@ translation teams, the attachment is the strings in the new RST pot file which cannot find an existing matched string.
You may take a look at it and let us know your feeling is.

Thank you.

Best regards
Ying Chun Guo (Daisy)

(See attached file: new strings all.po)


Andreas Jaeger <aj@suse.com> wrote on 2015/04/09 14:53:27:

> From: Andreas Jaeger <aj@suse.com>
> To: "openstack-i18n@lists.openstack.org" <openstack-i18n@lists.openstack.org>
> Cc: Anne Gentle <anne@openstack.org>
> Date: 2015/04/09 14:53
> Subject: [Openstack-i18n] User Guides Changes

>
> The two User Guide, Admin User Guide and End User Guide, have been
> converted from Docbook XML to RST. The conversion shouldn't have changed
> sentences but since markup has changed, strings for translation have
> changed as well.
>
> I've tried to merge the strings in transifex, so please have a look -
> and update the guides.
>
> I've marked the old guides as read-only in transifex, so that you cannot
> change them anymore but still can use them as reference. The
> documentation team will remove the old-guides from their project today.
>
> Transifex resources:
> Old End User Guide:
> https://www.transifex.com/projects/p/openstack-manuals-i18n/
> resource/user-guide/
>
> Old Admin User Guide:
> https://www.transifex.com/projects/p/openstack-manuals-i18n/
> resource/user-guide-admin/
>
> New RST User Guides (single resource for both books):
> https://www.transifex.com/projects/p/openstack-manuals-i18n/
> resource/user-guides/
>
> If there's anything else I can do, please speak up,
>
> Andreas
> --
>   Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>    SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>     GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
>         Graham Norton, HRB 21284 (AG Nürnberg)
>      GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> _______________________________________________
> Openstack-i18n mailing list
> Openstack-i18n@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n