How can we realize multilingual documentation?

[kozo2]

@ksnt previously translated the dash tutorial into Japanese. https://github.com/ksnt/Dash_Translation_into_Japanese https://community.plotly.com/t/can-i-translate-english-tutorial-into-japanese-one/8859

I would like to reflect @ksnt 's contribution to this repository. Please let me know, if you have any ideas for making multilingual documentation.

[ksnt]

Hi,

By the way, we can find some past discussions here: https://github.com/plotly/dash-docs/pull/77

Thank you.

[chriddyp]

@ksnt @kozo2 We would love to see multilingual documentation! The tricky part is coming up with the right architectural framework that remains easy & ergonomic to rapidly author and update documentation.

If either of you (or anyone else out there) is interested in this, then I'd encourage you to consider a chapter like https://dash.plotly.com/datatable/conditional-formatting and consider how to architect the code to handle multiple languages. You don't need to necessarily do the translation, but just consider the abstraction.

The code & text for this chapter is here: https://github.com/plotly/dash-docs/blob/master/dash_docs/chapters/dash_datatable/conditional_formatting/index.py

Feel free to make a work in progress PR to show or discuss different approaches.

[chriddyp]

For example, one option could be something like replacing

        rc.Markdown("""
        # Conditional Formatting
        Conditional formatting is provided through the `style_data_conditional`
        property.
        """),

with

        rc.Markdown(i18n("""
        # Conditional Formatting
        Conditional formatting is provided through the `style_data_conditional`
        property.
        """)),

and then that i8n function would collect all of the strings that were passed into it and, as part of some build process, write those strings as a big dictionary or set of translation files. Those would be language files in some easy-to-read and modify file format like. That is, the english strings would become the "keys" of the translation files and the translators would be responsible for providing translations in language files that would be separate from https://github.com/plotly/dash-docs/blob/master/dash_docs/chapters/dash_datatable/conditional_formatting/index.py itself. That'd keep https://github.com/plotly/dash-docs/blob/master/dash_docs/chapters/dash_datatable/conditional_formatting/index.py easy to modify and maintain for the english version of the website. Perhaps the language files would have some special marking to designate if they were "outdated" or not.

Then, there is the URL structure to consider. Perhaps each of these layout = definitions becomes a function with the language passed into it from the URL bar.

That's just one suggestion! I bet there are other ways to do this. But showing a proof of concept with a single chapter would be the place to start here.

These docs are just one big Dash app, so there is a lot of flexibility in how we approach this 🙂

Please comment below if you'd like to take a crack at this!

[kozo2]

@chriddyp Would this be okay?

index.py

from .i18n import i18n

i18n.py

EN2JA = {"""
        # Conditional Formatting

        Conditional formatting is provided through the `style_data_conditional`
        property. The `if` keyword provides a set of conditional formatting
        statements and the rest of the keywords are camelCased CSS properties.

        The `if` syntax supports several operators, `row_index`, `column_id`,
        `filter_query`, `column_type`, `column_editable`, and `state`.

        `filter_query` is the most flexible option when dealing with data.

        Here is an example of all operators:
        """:"""
        # 条件付き書式設定

        条件付き書式設定は`style_data_conditional`を通して提供されます。
        `if`キーワードは条件付き書式設定文のセットを提供し、
        残りのキーワードはキャメルケースの CSS プロパティです。

        `if`構文はいくつかの演算子 `row_index`, `column_id`,
        `filter_query`, `column_type`, `column_editable`, and `state`.
        をサポートします。

        `filter_query` はデータを取り扱うときに最も柔軟な選択肢です。

        ここでは、すべての演算子の例を示します:
        """}

def i18n(markdown):
    return EN2JA[markdown]