Add source examples for various used programming languages on how to add comments for translators

rakekniven commented 4 years ago

Often the strings lack of context. Nearly no comments for the translators are available. The docs at https://docs.nextcloud.com/server/latest/developer_manual/basics/front-end/l10n.html?highlight=translators#hints mention hints.

Target of the issue is to improve docs and ask all devs to add comments.

Nextcloud is using gettext for some languages. But there are more.

Does the syntax work for all languages? What about c++? Swift? vue?

Here I will collect working code:

PHP:

[x] Function works
[x] Docs updated

Code:

1 <ul id="translations">
2     <li id="add-new">
3         <?php
4             // TRANSLATORS Will be shown inside a popup and asks the user to add a new file
5             p($l->t('Add new file'));
6         ?>
7     </li>
8 </ul>

Javascript:

[x] Function works
[x] Docs updated

Same as for PHP

Code:

todo

Vue

[ ] Function works
[ ] Docs updated

Code:

C++ (Qt):

[x] Function works
[x] Docs updated

Code:

1 //: Example text: "Syncing 'foo.txt', 'bar.txt'"
2 fileProgressString = tr("Syncing %1").arg(allFilenames);

Link to source example: https://github.com/nextcloud/desktop/blob/master/src/gui/folderstatusmodel.cpp#L976

https://doc.qt.io/qt-5/i18n-source-translation.html#translator-comments

Android

[x] Function works
[x] Docs updated

Code:

1 <!-- Context comment for translator -->
2 <string name="simple_boards">Boards</string>

Issue for clarifying: https://github.com/stefan-niedermann/nextcloud-deck/issues/733
Android docs at Transifex: https://docs.transifex.com/formats/android-xml#section-developer-comments

Swift

[x] Function works
[x] Docs updated

Code:

1 /* The title on the navigation bar of the Scanning screen. */
2 "wescan.scanning.title"             = "Scanning";

Docs: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Strings/Strings.html

rakekniven commented 3 years ago

Hello @juliushaertl Can you help to find out how to add translator comments to vue files. The comments need to show up at Transifex. Started that topic last friday in the community chat. Maybe you remember :-)

juliusknorr commented 3 years ago

Thanks a lot for going over this. I'll need to have another look on how we could work around that limitation which mainly comes from the way we extract translations from vue files by manually building a fake file only containing the t() method calls.

We probably can extend the query to include the comments with including the line before or ideally find a tool that can extract proper pot files out of vue.js.

\<\!--(.*)\n(.*)\Wt\s*\(\s*'([\w]+)',\s*'(.+)'
\/\/(.*)\n(.*)\Wt\s*\(\s*'([\w]+)',\s*'(.+)'

An option would be to do it similarly as the vue components with https://github.com/nextcloud/nextcloud-vue/blob/master/build/extract-l10n.js but that does not seem to take comments into account by default but it should be possible.

rakekniven commented 3 years ago

Just downloaded the server repo (master) from GitHub today and did a search:

1 comment in js files ( // TRANSLATORS)
3 comments in php files ( // TRANSLATORS)

That's a lot 😁

juliusknorr commented 3 years ago

Might not catch multiline comments but I'm not even sure the other languages support that...

rakekniven commented 3 years ago

Started to add result to the docs. See https://github.com/nextcloud/documentation/tree/rakekniven-patch-1

rakekniven commented 3 years ago

Hello Julius, any news on that vue thing?

Valdnet commented 3 years ago

The topic started and the end of interest. Apparently, the developers don't really care about the applications being well translated by the translators :grimacing:.

rakekniven commented 3 years ago

@Valdnet

The topic started and the end of interest. Apparently, the developers don't really care about the applications being well translated by the translators 😬.

People underestimate us (the translators), I have staying power with something like this. The topic "vue" is still missing. Then I will write a message to all (!) Developers. Still have to find the right channel to reach everyone.

We can then also add comments to the source code. There will be a lot of PRs.

Hello @juliushaertl Julius, any news on that vue thing?

nextcloud / documentation