Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 14.5 KB

CONTRIBUTING.ja.md

File metadata and controls

204 lines (146 loc) · 14.5 KB
Raw

コントリビューション

XRP Ledger開発者ポータルへのコントリビューションをご検討いただきありがとうございます。

ぜひ、皆様の力をお貸しくださいますようお願いいたします。ご協力いただくことで、XRP Ledger（XRPL）への理解を深めることができます。

また、XRPLと併せて、インターレジャープロトコル（ILP）を学習することもおすすめいたします。ILPもRippleX開発者エコシステムの一部です。

皆様からのプルリクエストをお待ちしております。プルリクエストのレビュー工程をできるだけ円滑に進めるためにも、本ドキュメントをお読みいただき、記載されているガイドラインに従ってください。

ご提供いただいたコードは、XRP Ledgerプロジェクトの著作物となり、MITライセンスに基づいて提供いたします。

このサイトについて

XRPL開発者ポータルは、XRP Ledgerに関するドキュメントを幅広く提供します。これには、開発者がビルドを始めるためのサンプルコードなどの情報も含まれます。

リポジトリーのレイアウト

  • assets/ - サイトのテンプレートに使用する静的ファイル。
  • content/ - ドキュメントのビルドに使用するソースファイル。主にMarkdownです。
    • content/_code-samples/ - ドキュメントに使用するか、ドキュメントで参照するコードサンプル。可能であれば、完全に機能するか実行可能なスクリプトです。
    • content/_img-sources/ - ドキュメントで使用する画像のソースファイル。.uxfファイルはすべて、Umletで作成された図です。
    • content/_snippets/ - 再利用可能なMarkdownテキストのまとまり。Dactylプリプロセッサーを使用して他のコンテンツファイルに組み込みます。
  • img/ - ドキュメントのコンテンツに使用する画像。
  • tool/ - テンプレート、スタイルチェッカーのルール、その他スクリプト。
  • dactyl-config.yml - メインの設定ファイル。すべてのドキュメントのメタデータが含まれます。規約についての詳細は、設定の書式を参照してください。

プルリクエストを成功させるための要件

プルリクエストがレビューまたはマージの対象になるためには、各プルリクエストが以下を満たしている必要があります。

Dactylのセットアップ

このポータルは、Dactylを使用して構築されています。

DactylにはPython 3が必要です。以下のようにしてpipでインストールしてください。

sudo pip3 install dactyl

サイトのビルド

このリポジトリーでは、Dactylを使用して、すべてのドキュメントのHTML表示のバージョンをビルドできます。Dactylのセットアップが完了したら、プロジェクトのルートディレクトリーから以下のコマンドを使用してドキュメントをビルドできます。

dactyl_build

生成されたコンテンツがout/ディレクトリーに出力されます。これらのコンテンツは、ウェブブラウザーでファイルとして開くことも、ウェブサーバーで静的コンテンツとして提供することもできます。

同様に、ルートディレクトリーからリンクチェックやスタイルチェックを実行することもできます。

リンクチェックは、出力フォルダーを空にし、ドキュメントをビルドしてから実行する必要があります。

dactyl_link_checker

スタイルチェックは試験的なものです。

dactyl_style_checker

日本語サイトのビルド

ターゲットと出力先を指定してビルドしてください。

dactyl_build -t ja -o out/ja

日本語サイトの場合、生成されたコンテンツをウェブブラウザーでファイルとして開くことができません。ローカルHTTPサーバーやエディターの拡張機能(VSCodeであればLive Serverなど)を利用してください。

ローカルでHTTPサーバを利用する方法
  1. out直下で次のコマンドを実施しサーバーを起動する
python -m http.server
  1. ウェブブラウザーからlocalhostにアクセスする。 サーバー起動時にアサインされたポート番号を利用してください。

設定の書式

このリポジトリー内のテンプレートはdactyl-config.ymlファイルのメタデータを使用して、生成されたサイトをナビゲートする際のページ階層を生成します。ナビゲーションを正しく生成するには、ページの定義に適切なフィールドを含める必要があります。以下の例に、すべてのフィールドを指定したページを示します。

-   md: concept-authorized-trust-lines.md
    funnel: Docs
    doc_type: Concepts
    category: Payment System
    subcategory: Accounts
    targets:
        - local

ナビゲーションには、フィールドfunnel、doc_type、category、およびsubcategoryをこの順序（広範から詳細へ）で使用します。各階層では、新しい値が最初に記載されるページが、その階層の親かランディングとなります。（例えば、「Accounts」サブカテゴリーの親にはsubcategory: Accountsフィールドがあり、子より前に記載されている必要があります。）ランディングページの場合は、下位階層フィールドを省きます。（例えば、「Concepts」doc_typeのランディングページには、doc_typeフィールドは必要ですが、categoryフィールドは不要です。）

警告: いずれかのフィールドに入力ミスがあると、ページがナビゲーションに表示されないか、誤った場所に表示されるおそれがあります。

規約として、親ページには、親である階層と同じ名前が必要です。（例えば、Payment Systemカテゴリーのランディングページの名前はPayment Systemである必要があります。）mdをソースとするファイルの名前は、そのファイルの最初の行のヘッダーによって自動的に決まります。

Markdownソースコンテンツのないページの場合は、md行を省き、代わりに以下のフィールドを記載します。

フィールド 内容
name 人間が読めるページ名（プレーンテキストのみ）
html ページの出力ファイル名.htmlで終わり、ターゲット内で一意である必要があります。

翻訳

XRP Ledger開発者ポータルは主に英語で記載されているため、通常は英語版が最新かつ正確なバージョンです。しかし、XRP Ledgerのソフトウェアとコミュニティーの利用者を拡大するため、このリポジトリーには翻訳版のドキュメントも含まれています。他の言語を理解するコミュニティーのメンバーの皆様には、どうか開発者ポータルのコンテンツを母国語に翻訳していただけますようお願いいたします。

dactyl-config.ymlには、使用可能な各言語の「ターゲット」項目が含まれます。（2019年11月18日現在、使用可能な言語は英語と日本語です。）この項目には、テンプレートファイルで使用する文字列の辞書が含まれています。例:

-   name: en
    lang: en
    display_name: XRP Ledger Dev Portal
    # These github_ fields are used by the template's "Edit on GitHub" link.
    #  Override them with --vars to change which fork/branch to edit.
    github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
    github_branch: master
    strings:
        blog: "Blog"
        search: "Search site with Google..."
        bc_home: "Home"
        # ...

サポート対象の各言語のプロパティーをいくつか定義する最上位のlanguagesリストもあります。各言語のショートコードは、IETF BCP47に沿ったものである必要があります。例えば、英語は「en」、スペイン語は「es」、日本語は「ja」、簡体字中国語は「zh-CN」、繁体字中国語（台湾で使用）は「zh-TW」になります。display_nameフィールドでは、言語名をその言語で記載して定義します。prefixフィールドでは、その言語版のサイトへのハイパーリンクに使用されるプレフィックスを定義します。languagesのサンプルの定義を以下に示します。

languages:
   -   code: en
        display_name:English
        prefix: "/"
    -   code: ja
        display_name:日本語
        prefix: "/ja/"

同じdactyl-config.ymlファイルに、XRP Ledger開発者ポータルの各コンテンツページの項目が記載されています。ページが翻訳されている場合は、翻訳ごとに別個の項目があり、その翻訳「ターゲット」にリンクされています。ページがまだ翻訳されていない場合は、すべての対象に英語版が使用されます。各ページで、HTMLファイル名（htmlフィールド）とナビゲーションフィールド（funnel、doc_type、supercategory、category、およびsubcategory。それぞれ、指定される場合）は、どの言語版のページでも同じである必要があります。翻訳版のページで内容の異なるフィールドは、以下のとおりです（いずれの場合においても、そのフィールドが項目で使用される場合に限ります）。

  • name - ページのタイトル。通常は、Markdownソースファイルを使用しないランディングページや、開発者用ツールなどの独自のテンプレートを使用する特殊なページでのみ指定されます。通常、Markdownのファイルではこのフィールドが省かれます。Dactylはファイルの最初の行のヘッダーからタイトルを引き出すためです。
  • md - ページのソースコンテンツとして使用するMarkdownファイル。規約として、翻訳したMarkdownソースファイルには英語版と同じファイル名を使用する必要があります。ただし、ファイルの拡張子は英語版のように.mdのみでなく、.{language code}.mdとする必要があります。例えば、日本語の翻訳ファイルは.ja.mdで終わります。
  • blurb - ページの要約。このテキストは主にcategoryランディングページで使用されます。

以下の例に、server_infoメソッドページの英語の項目と日本語の項目を示します。

    -   md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
        html: server_info.html
        funnel: Docs
        doc_type: References
        supercategory: rippled API
        category: Public rippled Methods
        subcategory: Server Info Methods
        blurb: Retrieve status of the server in human-readable format.
        targets:
            - en

    -   md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
        html: server_info.html
        funnel: Docs
        doc_type: References
        supercategory: rippled API
        category: Public rippled Methods
        subcategory: Server Info Methods
        blurb: rippledサーバーについての各種情報を、人間が読めるフォーマットでサーバーに要求します。
        targets:
            - ja

翻訳されていないページの項目の例は以下のとおりです。

    -   md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
        html: source-and-destination-tags.html
        funnel: Docs
        doc_type: Concepts
        category: Payment System Basics
        subcategory: Transaction Basics
        blurb: Use source and destination tags to indicate specific purposes for payments from and to multi-purpose addresses.
        targets:
            - en
            - ja

最初にすべきこと

XRP Ledger開発者ポータルを任意の母国語に翻訳いただける場合は、XRP Ledgerの主要なプロパティーと機能について説明するXRP Ledgerの概要ファイルから始めてください。

ファイル名はxrp-ledger-overview.{language code}.mdで保存してください。{language code}はIETF BCP47の言語コードです。（例えば、スペイン語は「es」、日本語は「ja」、簡体字中国語は「zh-CN」、台湾で使用される繁体字中国語は「zh-TW」などです。）その後、このリポジトリーにファイルを追加するプルリクエストを開きます。リポジトリーのメンテナーが、サイトに言語を追加するために必要なその他のセットアップについてお手伝いします。

Markdownコンテンツのファイルについては、以下の規則に従ってください。

  • 改行には改行文字（\n）のみを使用します（Unix形式）。復帰改行文字（\r）は使用しないでください（Windows形式）。
  • UTF-8エンコーディングを使用します。バイトオーダーマークは使用しないでください。