[Gimp-docs] First experience with po's

[Ulf-D. Ehlert]

Hi Julien,

julien (Samstag, 27. Dezember 2008, 18:34):
> Here is my first experience using po's (po/fr/../doc.po,
> pot/../doc.pot, src/../doc.xml). I consider two cases:

> A - Translating only:
> No change in the help structure; no add, no deletion. Only
> translation of the strings.
> 	1- Using the po file is the simplest way.
> 		a/ First update this po to get strings that have changed by using
> the following command:
> msgmerge -U po/fr/../doc.po

Use "make po-fr"  or  "make po/fr/../doc.po".

> This will add changed strings that are marked with a "Fuzzy" comment.
> Edit this updated po files, searching for "Fuzzy".
> 		b/ When your file is OK, validate it with this command (being in
> the folder containing  doc.po):
> msgfmt -c --stat doc.po

Should we really add a make target for checking single po files?
Workaround:  "make xml-fr" - it this succeeds, the po file should be ok.

> This displays possible errors and some stats and generate a doc.mo
> file that is of no use here.

msgfmt will find only simple errors like missing quote (") characters 
etc., but it won't find DocBook errors, which are IMHO more likely.

> 		c/ make the "svn diff"
>
> 	2- You may want to work on a xml file rather than on a po:
> 		a/ update the po files you want to use as above
> 		b/ Create the xml files for your language (being in "trunk"):
> make -f Makefile.GNU xml-fr for example.
> This creates a xml folder in "trunk".
> 		c/ Edit the wanted xml file.

No! Edit the English xml file src/.../doc.xml.
"make validate" should work now, checking the English xml files.
Then try "make po-fr" and edit po/fr/.../doc.po.
Try "make xml-fr" to create (and thus validate) the French xml file(s).
Or "make xml/fr/.../doc.xml" to create just a single xml file.
"make xml/fr/.../doc.draft" (extension '.draft' insted of '.xml') should 
also work and should produce an HTML preview file.

> 		d/ We can't validate xml for the moment. But you can open the file
> in a web browser (Firefox) that will detect some errors.

"make xml/fr/.../doc.draft" should work, "make validate" too.

> Or copy the file in an old sandbox (before xml2po migration) and run
> make validate...:-(

No.

> 		e/ Transform your xml file to po (being in trunk):
> xml2po -e -o <path to doc.po> -r <path to your doc.xml>
> src/../doc.xml (the english doc.xml).

"make po-fr"  or  "make po/fr/../doc.po",
"make xml-fr".

> 		f/ cut-paste the doc.po file into the po directory.
> 		g/ Goto 1b

"Goto" considered harmful... ;-)

> B - Updating gimp-help-2
>
> 	1- Edit the src/../doc.xml file (english). 

Yes.

> 	Or edit a xml file in 
> your language and translate it after.

No!

> 	2- Validate it
> 	3- Transform the updated doc.xml file to doc.pot:
> xml2po -e -o doc.pot doc.xml

"make pot" will create pot/../doc.pot.

> 	4- Edit the doc.xml file in your language, validate it

No!

> 	5- goto 1e
>
> You may want to view your xml file in html. Waiting for Ulf's make
> html-fr

Just try "make html-fr" and report what's going wrong.

> , I use 
> $yelp file:///home/<user-id>/.../trunk/xml/<LANG>/doc.xml
> Unfortunately, images are not displayed by yelp. How to do?

I guess we can't use yelp. As far as I understand it, yelp will try to 
create the HTML manual on-the-fly, so this tool is only useful for 
small manuals.

For yelp we would have to create a new "mini" manual.

> I would be very pleased if you can provide a more simple way to work.

Translating only:
	1. "make po-fr" to be up-to-date
	2. edit po/fr/.../doc.po
	3. "make xml-fr" or "make xml/fr/.../doc.xml" to check the result
	4. "make xml/fr/.../doc.draft" to see an HTML preview
	5. "make status-fr" to see which po files have to be edited
	   [not yet implemented, but I will add this feature today]

Adding/changing English documents:
	1. edit src/.../doc.xml
	2. "make validate"

Adding/changing French documents:
	1. Don't! Just update the respective po files.

Of course there are still bugs and some of the command may fail...

Bye,
Ulf

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : /lists/gimp-docs/attachments/20081228/ecf12f0e/attachment.bin