Configuring Poedit

[mgeisler]

Thanks to @CoinEZ-JPN for looking at how to configure Poedit in #766 (comment):

morning, just sharing in case it may help others with similar issues;

• auto-conversion is a Mac setting
• to disable, follow these steps;

1. Open poedit
2. Go to Edit > Substitutions
3. Uncheck "Smart Quotes"
   Note: the focus may need to be in the "Translation" section to see toggle enabled

[mgeisler]

This was also brought up in #827 by @Throvn — I suggest we continue discussing it here.

Longer term, google/mdbook-i18n-helpers#27 will make it so that '\n' from the source Markdown files is turned into a ' ' in the PO files. I haven't released this version yet since I need to ensure that we can normalize the existing PO files to avoid losing work.

[Throvn]

This is definitely a welcome addition but I'm not too sure that it will solve the problem I'm currently having.

The problem I have is that my PoEdit seems to reformat already translated strings and inserts line breaks automatically. I've marked my PR from last week as WIP so you can see what I mean. #828
I didn't do a msgmerge or similar, so I don't think the base translation newlines have an impact on this.

[mgeisler]

My hope is that the reformatting will happen only once — but I'm not an expert in Poedit at all (I use Emacs myself to edit both the Markdown and PO files).

The automatic line breaks are okay, as long as people agree on where to put them 😄

[mgeisler]

@Throvn or @CoinEZ-JPN, can you figure out how to tell Poedit to stop updating the PO-Revision-Date and X-Generator PO headers?

[CoinEZ-JPN]

I won't be able to take a proper look until the weekend (also not very familiar with poedit), but sharing what I already know.

• regarding Revision-Date my suggestion would be to delete the date entirely so it looks something like this "PO-Revision-Date: \n" - the field will no longer update, and does not impact the larger project (at least from a quick check on localhost)
• BUT I just tried the same for X-Generator and it did not work (maybe add a pre-commit hook of some sort?)

Will look to make time over the next week.

[CoinEZ-JPN]

Thought about this. There doesn't seem to be anything within poedit that can be used. (or I just couldn't find it)
Can we simply exclude these lines using .gitattributes and .git/config?

For example in .gitattributes

*.po filter=someFilter

and in .git/config

[filter "combinedFilter"]
    clean = "grep -v 'PO-Revision-Date:' | grep -v 'X-Generator:'"

This will automatically exclude the lines with the specified strings from being committed, but will not delete from local.
It isn't the ideal solution, but there isn't anywhere else within the *.po range with the same headers so I thought worth asking.

[mgeisler]

Hi @CoinEZ-JPN, thanks for finding those commands. I'm hesitant to add something like this since it adds extra complexity (and I don't know if it will work on Windows).

My impression is that the merge conflicts due to these fields have been easy to resolve, but I might be wrong?

[rastringer]

Just wonder if we all have different settings for wrap in poedit (settings->advanced). I have mine at the default 79 (on Mac), and preserve formatting of existing files ticked. I notice when other contributors make changes to lines I've contributed, the bulk of the PR is different line wrapping.

[mgeisler]

Hi folks, I've tested this a bit myself now. I see the following behavior:

• With "Preserve formatting of existing files":
  • Poedit will look at the file to guess the wrapping width! The "Wrap at: 79" setting is ignored. For the Danish translation, the wrapping width becomes 101 columns, for the German translation is becomes 108 columns. This is clearly not what we want since the width setting is applied to all entries!
• With "Preserve formatting of existing files" turned off:
  • With "Wrap at: 79": Poedit will wrap the file by calling out to msgcat --width 79.
  • With "Wrap at" disabled: Poedit will call msgcat --no-wrap.

By the way, I ended up tracing this with strace -f -e trace=%process poedit — that quickly made everything clear 😄

Based on all this, it's now clear that we need to normalize the PO files in a way compatible with these calls to msgcat. Luckily, we can call msgcat ourselves to format the files.

We should do two things:

1. We uncheck the "Preserve formatting of existing files" option to make Poedit call out to msgcat --width 79 consistently. The long URLs will otherwise mess things up: even if we wrap the messages ourselves with msgcat --width 79, Poedit will see the long lines and call msgcat --width 123 next time.
2. We normalize the German translation with a suitable line width, see de: normalize line width to 79 columns #954. The Poedit default of 79 columns is nice since it leaves space for a + or - diff marker in the terminal. I suggest we keep it since it will be less to communicate to new people setting up Poedit.
3. After committing the normalized translation, we create a new PR with the changes from de: Translation until chapter 9.1 #828. When saving, Poedit will run the file through msgcat --width 79 and so we will get a nice and useful diff. @Throvn, can you make this PR after de: normalize line width to 79 columns #954 is merged? You just need to copy your de.po file to the side, grab the latest main, move the de.po file back, re-save with Poedit after disabling the "Preserve formatting of existing files" option.

We could update mdbook-i18n-helpers to wrap the messages.pot file better, but it would still suffer from the problem of long URLs. I guess the only solution to that would be to remove the URLs from the extracted text.

[henrif75]

I guess it's ok to wrap lines with URLs? e.g.:
"* Test the above code on the [Rust Playground](https://play.rust-lang.org/?" "version=stable&mode=debug&edition=2021&gist=3ce2ad13ea1302f6572cb15cd96becf0)."

[mgeisler]

Yes, that's perfectly fine — you're basically free to format the PO file in any way that is useful to you. It should just work with the tools you and your colleagues use 😄

@henrif75, would you be up for adding some text to TRANSLATIONS.md about how to configure Poedit?

[henrif75]

SG, will work on it @mgeisler

[mgeisler]

Thanks!

[henrif75]

Something that I forgot was the smart quotes | dashes. Should I add another step to turn them off?
@mgeisler

[mgeisler]

I think those are less important: the code snippets will fail in CI and people can just change them back. The gigantic diffs are much harder to deal with — practically impossible if you've already saved the file and have a mix of translation updates and reformatting.