Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The help text for [>>>] toggle always in English #23

Open
jfine2358 opened this issue Aug 21, 2018 · 7 comments
Open

The help text for [>>>] toggle always in English #23

jfine2358 opened this issue Aug 21, 2018 · 7 comments

Comments

@jfine2358
Copy link

@jfine2358 jfine2358 commented Aug 21, 2018

See, for example, https://docs.python.org/fr/3/tutorial/introduction.html. It applies to all interactive code examples.

This is https://bugs.python.org/issue34452, transferred here, as a third party issue. It is related to
PEP 545 - Python Documentation Translations.

Here's what I've found. The purpose of python_docs_theme/static/copybutton.js is

Add a [>>>] button on the top-right corner of code samples to hide the >>> and ... prompts and the output and thus make the code copyable.

To do this it contains code

    var hide_text = 'Hide the prompts and output';
    var show_text = 'Show the prompts and output';

Somehow, this text needs to be internationalised.

@theacodes
Copy link
Collaborator

@theacodes theacodes commented Aug 21, 2018

Tricky. Not sure how to internationalize text within a JS file.

We could see about moving that text into the Jinja templates and use JS to show/hide it.

@jfine2358
Copy link
Author

@jfine2358 jfine2358 commented Aug 21, 2018

Thank you for your prompt attention. It's not something I've done, either. I looked at view-source:https://docs.python.org/3/tutorial/introduction.html. It contains

<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/switchers.js"></script>

Perhaps best not to change this. Instead load an extra file, something like static/fr_text.js. that contains all the language variable text. This file should I think be part of the FRench translation of the docs (or generated from such). Once you've got that, use it in copybutton.js.
There are libraries and tools associated with GNU gettext, that will help you with this. I hope this helps.

@theacodes
Copy link
Collaborator

@theacodes theacodes commented Aug 21, 2018

I've honestly never done translation stuff, but I'm happy to give it a shot once I find some time.

In the meantime, it would be awesome if anyone with specific experience here can help.

@terryjreedy
Copy link
Member

@terryjreedy terryjreedy commented Aug 21, 2018

@ccwang002
Copy link
Contributor

@ccwang002 ccwang002 commented Feb 16, 2019

While is it hard to add translation directly into the javascript file, I was wondering if it is possible to add the strings in a HTML file, and use jQuery to fetch the translated string back.

Sphinx has the ability to extract sentences from HTML. For example, we could add the strings into layout.html, on which all the HTML pages are based:

<div style="display: none">
    <p id="copybutton-hide-text">{% trans %}Hide the prompts and output{% endtrans %}</p>
    <p id="copybutton-show-text">{% trans %}Show the prompts and output{% endtrans %}</p>
</div>

And in the copybutton.js, we try to fetch the translated string and provide the English fallback:

// search for the translated prompt strings and fallback to use English if not found
var hide_text_p = $('#copybutton-hide-text');
var hide_text = hide_text_p.length > 0 ? hide_text_p.text() : "Hide the prompts and output";
var show_text_p = $('#copybutton-show-text');
var show_text = show_text_p.length > 0 ? show_text_p.text() : "Show the prompts and output";

I have some questions about this approach:

  1. Where in the HTML template should we place the translated string? In block footer or header?
  2. Should we instead interpolate the javascript itself, say, treating copybutton.js like a Sphinx template so it directly supports i18n?
  3. Will there be a certain configuration where a user might accidentally see this div and get confused?

I can submit a PR if people think the approach is reasonable.

@theacodes
Copy link
Collaborator

@theacodes theacodes commented Feb 17, 2019

ccwang002 added a commit to ccwang002/python-docs-theme that referenced this issue Feb 17, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.