Home → Problems →

Wrong translation of README selected by default

• Edit

dan.j.allen

23 Mar, 2019 07:49 AM

The README for the asciidoctor gem is being displayed in Japanese instead of English. This is happening because the README-jp.adoc file is being used instead of README.adoc. Unfortunately, most visitors expect the README to be in English. Can you please tell me how I can fix this problem?

See https://www.rubydoc.info/gems/asciidoctor/2.0.0

1. Support Staff 1 Posted by lsegal on 23 Mar, 2019 08:00 AM

   

   Sure thing!

   By default, YARD picks the first matching README file as part of the README* glob. You can override the README file by specifying a first extra file or using --readme README.adoc in your .yardopts file.

   Hope that helps!

   • Edit

2. 2 Posted by Dan Allen on 23 Mar, 2019 08:25 AM

   

   Thanks for the quick reply.

   > You can override the README file by specifying a first extra file or using --readme README.adoc in your .yardopts file.

   I do that already. https://github.com/asciidoctor/asciidoctor/blob/master/.yardopts

   Do I have to include the .yardopts file in the gem?

   • Edit

3. Support Staff 3 Posted by lsegal on 23 Mar, 2019 08:30 AM

   

   Yes, the .yardopts must be packaged with the gem for rubydoc to pick it up for gem docs hosting.

   • Edit

4. 4 Posted by Dan Allen on 23 Mar, 2019 08:32 AM

   

   Argh. That means there's no way for me to fix it for any gem already released.

   Is there any chance you'd be willing to change the glob to only match the basename README (keeping the wildcard only on the file extension)? Surely that's the behavior users expect. (That's also consistent with how other systems work, like npm and yarn).

   • Edit

5. Support Staff 5 Posted by lsegal on 23 Mar, 2019 11:33 PM

   

   Is there any chance you'd be willing to change the glob to only match the basename README (keeping the wildcard only on the file extension)? Surely that's the behavior users expect

   I think this conversation would be better had as an issue YARD itself (https://github.com/lsegal/yard/issues). I think I'd be open to discussions about how globs are sorted so as to choose a more reliable default, but we couldn't exclude README-* files from the glob altogether, since that would be a breaking change, and likely not the expected behavior either. If you're interested, a PR to sort README and README.* ahead of other README files would be considered.

   • Edit

6. 6 Posted by Dan Allen on 24 Mar, 2019 12:11 AM

   

   I can follow up there.

   What's the use case for only having README files with a hyphenated suffix? Obviously, there may be additional files with a suffix for translations, but why would you ever want those to be selected anyway? The only case I can think of is someone adds the "-en" suffix to the English version instead of using the basename README. But that seems highly unlikely. Perhaps I'm just not aware of this practice.

   • Edit