mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-12-06 17:27:57 +00:00
chore: rename deprecated i18n to l10n
This commit is contained in:
Vova Rutskyi
committed by
amarantha-k
amarantha-k
parent
6cbb3a036f
commit
9a0c010600
@@ -0,0 +1,36 @@
|
||||
---
|
||||
html: creating-diagrams.html
|
||||
parent: contribute-documentation.html
|
||||
seo:
|
||||
description: ライトモードとダークモードの設定で適切に動作する図を作成します。
|
||||
---
|
||||
# 図の作成
|
||||
|
||||
このサイトには、SVGの図をライト・ダークモード用に自動的に再カラーリングするコードが含まれています。これは単に画像を反転させるだけではありません。再カラーリングは（ボトムライトに見えないように）グラデーションを同じ方向に保ち、色をその逆ではなくテーマに合った同等なものに置き換えます。例えば、"Ripple blue"は、その逆のオレンジではなく、XRPLグリーンに再カラーリングされます。
|
||||
|
||||
|
||||
|
||||
テーマを意識した再カラーリングでは、図のSVG形式の単一のソースファイルを使用し、CSSを使用して現在のテーマ（明暗）に合わせて再カラーリングされた図を生成します。ユーザがテーマを変更すると、図は即座にそれに合わせて変更されます。
|
||||
|
||||
テーマに対応した図をドキュメントに含めるには、以下のような構文で`include_svg`フィルタを使用します。
|
||||
|
||||
```jinja
|
||||
[{% inline-svg file="/docs/img/anatomy-of-a-ledger-complete.svg" /%}](/docs/img/anatomy-of-a-ledger-complete.svg "図1：XRP Ledgerの要素")
|
||||
```
|
||||
|
||||
この構文の前後は空行にしてください。該当のSVGファイルは、リポジトリのトップレベルにある[`img/`](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img)フォルダか、そのサブフォルダにあるはずです。2番目の引数は _表題_ で、ユーザが図の上にマウスを置いたときに表示されます。
|
||||
|
||||
作成されたSVGファイルはMarkdownファイルに直接挿入されます。1点制限事項として、箇条書きリストやテーブルのような他のMarkdown構造の中では使用することはできません。
|
||||
|
||||
{% admonition type="info" name="注記" %}
|
||||
フィルタのソースコードは[`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py)です。これは`lxml`がサイトを構築するための依存関係の一つである理由でもあります。
|
||||
{% /admonition %}
|
||||
|
||||
## Making Diagrams
|
||||
|
||||
図を作成する際には、再カラーリングが正しく適用されるように注意する必要があります。そうしないと、もう一方のテーマ用に再カラーリングしたときに、一部の要素が見えなくなる可能性があります(例えば、白地に白や黒地に黒など)。テーマを考慮したダイアグラムのコードは、[Umlet](https://www.umlet.com/)または[Google Draw](https://docs.google.com/drawings/)のいずれかを使用して作成され、SVGとしてエクスポートされた図をサポートしています。また、図を作成する際には、以下のガイドラインに従ってください。
|
||||
|
||||
- デフォルトでライトモード用の図を作成します。透明な背景色を使用してください。
|
||||
- テーマ対応ダイアグラムのコードがマッピングしている色のみを使用します。色の完全なリストを含む、このためのコードは[`styles/_diagrams.scss`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/_diagrams.scss)にあります。必要であれば、SCSSコードを拡張することで、新しい色を追加することができます。(作業が終わったら、CSSを再エクスポートすることを忘れないでください。[style README](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/README.md)をご覧ください)。
|
||||
- 可能な限り、埋め込みアイコン/画像の代わりにベクター図形を使用してください。画像の上にテキストを配置する必要がある場合は、テキスト要素に無地の背景を追加し、テーマがマッピングしている色のいずれかを使用してください。
|
||||
- テキストを含む透明な要素を、異なる背景色を持つ要素の上に重ねないでください。テキストを含む要素に直接背景色を適用してください。
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
html: documentation-translations.html
|
||||
parent: contribute-documentation.html
|
||||
seo:
|
||||
description: このウェブサイトにある文書の翻訳に貢献し、維持する方法を学びましょう。
|
||||
---
|
||||
# 翻訳
|
||||
|
||||
XRP Ledger Dev Portalは大部分が英語で書かれているため、一般的には英語版が最新かつ正確なバージョンです。しかしながら、XRP Ledgerのソフトウェアとコミュニティへのリーチを広げるために、このリポジトリには翻訳版のドキュメントも含まれています。私たちは、他の言語を理解するコミュニティのメンバーが、開発ポータルの内容を母国語で翻訳することを大いに歓迎します。
|
||||
|
||||
`dactyl-config.yml`には利用可能な言語ごとに"target"項目があります(現在、利用可能な言語は英語と日本語です)。このエントリには、次のようにテンプレートファイルで使用される文字列の定義が含まれます。
|
||||
|
||||
```yaml
|
||||
- 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](https://tools.ietf.org/html/bcp47)に従ったショートコードでなければなりません。例えば、"en"は英語、"es"はスペイン語、"ja"は日本語、"zh-CN"は簡体字中国語、"zh-TW" は繁体字中国語 (台湾で使用) などです。`display_name`フィールドはその言語でネイティブに書かれた言語名を定義します。`prefix`フィールドはその言語のサイトへのハイパーリンクで使用する接頭辞を定義します。次に`languages`の定義例を示します。
|
||||
|
||||
```yaml
|
||||
languages:
|
||||
- code: en
|
||||
display_name: English
|
||||
prefix: "/"
|
||||
- code: ja
|
||||
display_name: 日本語
|
||||
prefix: "/ja/"
|
||||
```
|
||||
|
||||
同じ`dactyl-config.yml`ファイルには、XRP Ledger Dev Portalの各コンテンツページのエントリがあります。ページが翻訳されている場合、各翻訳ごとに個別の項目があり、その翻訳の“ターゲット"にリンクされています。ページがまだ翻訳されていない場合、すべてのターゲットで英語版が使用されます。(新しいページが英語のみ追加され、他の言語が提供されない場合、リンクチェッカーはそれをリンク切れとして報告します。)
|
||||
|
||||
ページを翻訳するということは、そのページのエントリを他の言語と分割するということです。ページのメタデータは`dactyl-config.yml`ファイルか、ページのMarkdownファイルの先頭にあるfrontmatterに設定します。
|
||||
|
||||
| フィールド | 備考 |
|
||||
|----------|------|
|
||||
| `html` | ページのHTMLファイル名。慣例により、これはすべての言語バージョンで同じであるべきです。 |
|
||||
| `md` | ページのMarkdownソースファイル。翻訳されたMarkdownソースファイルは英語版と同じファイル名を使用してください。ただし、拡張子は英語版の`.md`ではなく、`.{言語コード}.md`を使用してください。例えば、日本語の翻訳ファイルの拡張子は `.ja.md` です。 |
|
||||
| `blurb` | ページの簡単な要約。これは翻訳されるべきです。このテキストは、検索エンジン最適化のためのメタデータや、自動生成されるランディングページで使用されます。 |
|
||||
|
||||
`server_info`メソッドページの英語と日本語の記入例：
|
||||
|
||||
```yaml
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
|
||||
targets:
|
||||
- ja
|
||||
```
|
||||
|
||||
翻訳されていないページの記入例：
|
||||
|
||||
```yaml
|
||||
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
```
|
||||
|
||||
## 始めるにあたって
|
||||
|
||||
XRP Ledger Dev Portalをあなたの母国語に翻訳したい場合は、まず{% repo-link path="docs/concepts/introduction/what-is-the-xrp-ledger.md" %}"What is the XRP Ledger?" file{% /repo-link %}から始めてください。
|
||||
|
||||
このファイルを`xrp-ledger-overview.{言語コード}.md`として保存します。ここで`{言語コード}`は[IETF BCP47](https://tools.ietf.org/html/bcp47)の言語コードです。(例えば、スペイン語は"es"、日本語は"ja"、簡体字中国語は"zh-CN"、台湾で使われている繁体字中国語は"zh-TW"などです)。そして、あなたのファイルをこのリポジトリに追加する[プルリクエスト](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)を作成してください。リポジトリメンテナの誰かが、サイトに言語を追加するために必要なその他の設定を手伝ってくれるでしょう。
|
||||
|
||||
Markdownコンテンツファイルでは、以下の規則に従ってください。
|
||||
|
||||
- 改行文字(`\n`)のみ（Unixスタイル）。キャリッジリターン文字(`\r`)は使用しないでください（Windowsスタイル）。
|
||||
- UTF-8エンコーディングを使用してください。バイトオーダーマークの使用は避けてください。
|
||||
374
@l10n/ja/resources/contribute-documentation/index.md
Normal file
374
@l10n/ja/resources/contribute-documentation/index.md
Normal file
@@ -0,0 +1,374 @@
|
||||
---
|
||||
html: contribute-documentation.html
|
||||
parent: resources.html
|
||||
seo:
|
||||
description: XRP Ledgerドキュメントのコントリビューションガイドです。
|
||||
---
|
||||
# ドキュメントへの貢献
|
||||
|
||||
XRP Ledger開発者ポータルへの貢献を検討いただきありがとうございます！
|
||||
|
||||
|
||||
私たちは、あなたが興味を持ってくださっていることにとても感動しています。XRP Ledger(XRPL)へ貢献することは、XRPLついて学ぶ素晴らしい機会です。
|
||||
|
||||
私たちはあなたのプルリクエストを喜んでレビューします。プロセスをできるだけ円滑に進めるため、このドキュメントを読み、記載されているガイドラインに従ってください。
|
||||
|
||||
## 当サイトについて
|
||||
|
||||
XRPL Dev Portalでは、開発者が開発を開始するためのサンプルコードやその他の情報を含む、XRP Ledgerの包括的なドキュメントを提供しています。
|
||||
|
||||
本プロジェクトの公式リポジトリは<https://github.com/XRPLF/xrpl-dev-portal>となっています。投稿の著作権はそれぞれの投稿者に帰属しますが、MIT[ライセンス](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE)の下で提供されなければなりません。
|
||||
|
||||
## リポジトリの構成
|
||||
|
||||
- `_api-examples/` - APIリクエストやレスポンスのサンプル(特にドキュメントで使用されているもの)
|
||||
- `_code-samples/` - ドキュメントで使用されているサンプルコード(可能な限り完全に動作するスクリプト)
|
||||
- `@l10n` - 英語以外の翻訳コンテンツ
|
||||
- `@theme` - MarkdocのコンテンツやReactのカスタムページで使用されるコンポーネントのオーバーライドやカスタムコンポーネント
|
||||
- `about/` - 概要セクションのソースファイル
|
||||
- `blog/` - XRPL開発者ブログのソースファイル
|
||||
- `community/` - コミュニティセクションのソースファイル
|
||||
- `docs/` - ドキュメントをビルドするためのソースファイル(ほとんどがMarkdownファイル)
|
||||
- `docs/_snippets/` - ドキュメント内で再利用可能なテキスト
|
||||
- `docs/img/` - ドキュメント内で利用する図やその他の画像
|
||||
- `docs/img/_sources/` - ドキュメント内で利用する画像のソースファイル(存在する場合)
|
||||
- `locale/` - **廃止** 以前利用されていた翻訳用のファイル
|
||||
- `resources/` - リソースセクションのソースファイル
|
||||
- `shared/` - CodeMirrorなどの依存関係の設定ファイル
|
||||
- `static/` - Webサイトのテンプレートやテーマで使用される静的ファイル
|
||||
- `styles/` - カスタムCSS用のSCSSのソースファイル
|
||||
- `redirects.yaml` - 以前利用されていたパスから現在のコンテンツへのリダイレクトの定義
|
||||
- `redocly.yaml` - Webサイトにの主要な設定ファイル
|
||||
- `sidebars.yaml` - ドキュメントおよびリソースセクションのサイドバーの定義
|
||||
- `top-nav.yaml` - ナビゲーションバーの定義
|
||||
|
||||
|
||||
## プルリクエストが承認されるための条件
|
||||
|
||||
レビューやマージが承認される前に、それぞれのプルリクエストは以下の条件を満たしていなければなりません。
|
||||
|
||||
- インテグレーションテストに合格すること。
|
||||
- レビューの準備が整うまで、[Draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)としてください。
|
||||
- このリポジトリの[コード規約](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE-OF-CONDUCT.ja.md)を遵守してください。
|
||||
|
||||
## Redoclyのセットアップ
|
||||
|
||||
このポータルはRedocly Realmを使用して構築されています。Realmは現在クローズドベータ版です。ローカル開発環境にインストールするには、Node.js(バージョン20が推奨)とNPMが必要です。
|
||||
|
||||
次のコマンドを実行して、Realmとその他の必要な依存関係をインストールできます。
|
||||
|
||||
```sh
|
||||
npm i
|
||||
```
|
||||
|
||||
## サイトの構築
|
||||
|
||||
依存関係のインストール後、次のコマンドを実行してローカル開発サーバを起動できます。
|
||||
|
||||
```sh
|
||||
npm run start
|
||||
```
|
||||
|
||||
ブラウザでhttp://localhost:4000/にアクセスしてプレビューを表示できます。
|
||||
|
||||
|
||||
## 設定ファイルのフォーマット
|
||||
|
||||
Realmの設定ファイルは、サイト内のナビゲーション要素を生成するために使用されます。これには、ヘッダー、フッター、サイドバー、パンくずリストが含まれます。
|
||||
|
||||
新しいページを追加する場合、そのページを`sidebars.yaml`ファイルに追加する必要があります。ドキュメントとブログ用のサイドバーのファイルがあります。以下は、ネストされた子ページがないページの項目の例です。
|
||||
|
||||
```yaml
|
||||
- page: concepts/consensus-protocol/index.md
|
||||
```
|
||||
|
||||
Markdownファイルのページは、[frontmatterスタンザ](#frontmatterのフィールド)で始まる必要があります。
|
||||
|
||||
### 規約
|
||||
|
||||
ページを作成する際には、以下の規約に従ってください。
|
||||
|
||||
- HTMLのファイル名とMDのファイル名は、拡張子を除いて完全に一致していなければなりません。ファイル名は"and"や"the"のような単語を含め、ページのタイトルと密接に一致する必要がありますが、スペースや句読点の代わりにハイフンを使用し、すべて小文字にする必要があります。例えば、`cash-a-check-for-an-exact-amount.md`のようにします。ページのタイトルを変更した場合は、ファイル名も変更する必要があります。(すでに別のURLで公開されている場合は、古いURLからのリダイレクトを残してください)
|
||||
- カテゴリ内のページは、そのカテゴリの名前のサブフォルダに配置されるべきですが、親ディレクトリにも同じ単語が含まれている場合は、より簡潔にすることができます。ファイル名は`index.md`で、タイトルはフォルダ名に似ている必要があります。例えば、"Protocol Reference"のインデックスページは`references/protocol/index.md`にあります。
|
||||
- 常にh1ヘッダーでページを始めます。
|
||||
- ページの一番上のh1アンカーにはリンクせず、アンカーなしでページ自体にリンクしてください。これは翻訳時のリンク切れを防ぐのに役立ちます。以降のヘッダーへのリンクは問題ありません。
|
||||
- ページのタイトルに書式( _斜体_ や`コード`など)を使わないでください。
|
||||
- Markdownファイルのテキストを折り返さないでください。
|
||||
- コードサンプルの場合、1行は80文字以下になるようにしてください。
|
||||
- 迷ったら、[Ciro SantilliのMarkdownスタイルガイド (Writability Profile)](https://cirosantilli.com/markdown-style-guide/)に従ってください。
|
||||
- Markdownやコードサンプルでは、インデントにタブ文字を使用しないでください。**JavaScript**のコードサンプルでは、1字下げにつき2個のスペースを使用してください。
|
||||
- テキストファイルは改行文字で終わるようにしてください。(一部のテキストエディタはこれを自動的に処理します。)ファイルはBOMなしのUTF-8でエンコードしてください。
|
||||
|
||||
### 新機能
|
||||
|
||||
新機能を文書化する場合、その機能が導入されたプログラムのバージョンを示すバッジを含めてください。バッジタグは以下の構造です。
|
||||
|
||||
`{badge href="myurl" date="<リリース日>"}新規: <プログラム> <バージョン番号>{% /badge%}`
|
||||
|
||||
例えば次のようなバッジ定義になります。
|
||||
|
||||
`{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}新規: Clio v2.0.0{% /badge %}`
|
||||
|
||||
次のように表示されます。 {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}新規: Clio v2.0.0{% /badge %}
|
||||
|
||||
When updating a feature, replace _New in:_ with _Updated in:_. For example, the following badge definition:
|
||||
|
||||
機能の更新の場合、_新規:_ を _更新:_ に置き換えてください。例えば、次のバッジ定義となります。
|
||||
|
||||
`{% badge href="https://github.com/XRPLF/clio/releases/tag/2.1.0" date="May 4, 2024" %} 更新: Clio v2.1.0{% /badge %}`
|
||||
|
||||
次のように表示されます。 {% badge href="https://github.com/XRPLF/clio/releases/tag/2.1.0" date="May 4, 2024" %} 更新: Clio v2.1.0{% /badge %}
|
||||
|
||||
2年以上前の新規/更新バッジは削除するのがベストプラクティスです。
|
||||
|
||||
### 技術用語
|
||||
|
||||
以下の単語やフレーズを説明通りに使用してください。
|
||||
|
||||
| 用語 | 避けるべき用語 | 備考 |
|
||||
|-------------------|----------------|-------|
|
||||
| API, APIs | API's, RPC | Application Programming Interface (アプリケーション・プログラミング・インターフェース)、ソフトウェアが他のソフトウェアと接続するための機能と定義のセット。 |
|
||||
| コアサーバ, XRP Ledgerのコアサーバ | `rippled` | `rippled`という名前は近い将来廃止される可能性が高いので、より一般的な名前で呼ぶことを推奨します。必要なときは、`rippled` をすべて小文字で、コードフォントで呼んでください。(発音は "リップルディー" で、"d" は UNIX の伝統に従って"daemon"を意味します)。
|
||||
| 金融機関 | 銀行, FI, PSP (決済サービスプロバイダ) | この用語は、_銀行_ や他の用語よりも幅広いビジネスを包含し、業界の専門用語の理解に依存しません。 |
|
||||
| レジャーエントリ | レジャーオブジェクト, ノード | XRP Ledgerの状態データ内の単一のオブジェクト。_レジャーオブジェクト_ という用語は、これらの一つを指すこともあれば、レジャー全体を指すこともあります。レジャーの状態データはグラフとして想定できるため、_ノード_ という用語が使われることもありましたが、_ノード_ には他の用途もあるため、混乱を招きます。 |
|
||||
| 流動性提供者 | マーケットメイカー | 2つの通貨または資産間の売買を提供し、多くの場合、取引間の価格差から利益を得る企業または個人。マーケットメーカーという用語は、法域によっては特定の法律上の定義があり、すべての同じ状況で適用されるとは限りません。 |
|
||||
| 悪質業者 | ハッカー | 個人、組織、または自動化されたツールなどによる、機密情報の取得、暗号化の解除、サービスの拒否、その他の安全なリソースへの攻撃を試みる可能性のあるもの。 |
|
||||
| PostgreSQL | Postgres | リレーショナルデータベース・ソフトウェアの特定のブランド。非公式な短いバージョンではなく、常に完全な名前を使用します。 |
|
||||
| オーダーブック | オファーブック | マッチングされ約定されるのを待っているトレード注文のコレクション。通常は取引レートごとにソートされています。 |
|
||||
| サーバ | ノード | サーバとは、ソフトウェアやハードウェアのことで、特にXRP Ledgerのピアツーピアネットワークに接続するものを指します。_ノード_ という用語はこの目的のために使われることもありますが、グラフのエントリやJavaScriptインタプリタであるNode.jsなど、他の意味でも多用されます。 |
|
||||
| ステーブルコイン発行者 | ゲートウェイ | 発行者とは、XRP Ledgerにおいてトークンを発行する組織です。ステーブルコインとは、発行者が外部の資産（例えば不換紙幣）に完全に裏付けられていることを約束しているトークンのことで、ステーブルコインの発行者は、その2つの資産を（場合によっては手数料を払って）交換する入出金操作を提供します。以前は、このユースケースを表現するために（特にリップル社によって）_ゲートウェイ_ という用語が使用されていましたが、業界の他の部分は代わりに _ステーブルコイン発行者_ を採用しました。 |
|
||||
| トランザクションコスト | トランザクション手数料 | XRP Ledgerでトランザクションを送信するために消費されるXRPの金額。これはトランザクションの`Fee`フィールドで指定されますが、_手数料_ という用語は誰かにお金を支払うことを意味するため、_コスト_ の方が望ましいです。 |
|
||||
| トークン | IOU, issuances, issues, 発行済み通貨 | XRP Ledgerのトークンは、_IOU_ という名前から想像されるように、レジャーの外部にある価値を表すことはできません。必要であれば、_代替可能トークン_ を使用して、非代替性トークン(NFT)と区別してください。 |
|
||||
| ウォレット | ウォレット | 文脈によっては、_ウォレット_ はハードウェア、ソフトウェア、暗号鍵ペア、またはオンラインサービスを指します。意味が明確になるように十分な文脈を提供するか、_キーペア_ や _クライアントアプリケーション_ などの別の表現を使用してください。 |
|
||||
| XRP | Ripple, リップル | XRP Ledgerのネイティブデジタルアセットまたは暗号通貨。XRPはレジャーの外部の価値を表すトークンではありません。 |
|
||||
| XRP Ledger | Ripple, リップル, Ripple Network, リップルネットワーク, RCL | XRP Ledgerは、過去に様々な場面で「リップルネットワーク」や「リップルコンセンサスレジャー」あるいは「RCL」と呼ばれていました。これらの名称は、コアサーバのリファレンス実装を開発しているRipple(Ripple Labs)の社名と類似しているため、紛らわしく、廃止されました。 |
|
||||
| XRPL | XRPL | _XRP Ledger_ の略です。_XRPL_ は不明瞭で、_XRP_ のタイプミスのように見えることがあります。 |
|
||||
|
||||
## Frontmatterのフィールド
|
||||
|
||||
***Note: Realmのfrontmatter仕様の詳細は完全には文書化されていません。Realmがクローズドベータを終了したら、リンクを更新する必要があります。***
|
||||
|
||||
MarkdownファイルのFrontmatterには、以下のような内容が含まれます。
|
||||
|
||||
```yaml
|
||||
---
|
||||
metadata:
|
||||
indexPage: true # 自動生成された子ページのリストを含めたい場合、追加してください。
|
||||
seo:
|
||||
description: rippledはXRP Ledgerを管理するコアとなるピアツーピアサーバです。このセクションでは、rippledサーバの基本的な機能の背景にある「要素」と「その理由」を学ぶのに役立つ概念について説明します。
|
||||
---
|
||||
```
|
||||
|
||||
サイト内の一部のページには、以前の(Dactyl)ツールチェーンからのメタデータが残っている場合があります。これらのフィールドは効果がないため、新しいページから省略することができます。
|
||||
|
||||
### 次へと前へのボタン
|
||||
|
||||
ドキュメントとブログページには、ページの下部に「次へ」ボタンと「前へ」ボタンがあります。
|
||||
|
||||
これらのボタンが不要な場合は、ページのfrontmatterを更新して無効にすることができます。
|
||||
|
||||
```yaml
|
||||
---
|
||||
navigation:
|
||||
nextButton:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
## Markdocのコンポーネント
|
||||
|
||||
これらのファイルは[Markdoc](https://markdoc.dev/)で処理されるため、`{% ... %}`構文で特別なタグを含めることができます。Redoclyの組み込みタグに加えて、このリポジトリには`/@theme/markdoc/`に定義されたいくつかのカスタムタグがあります。
|
||||
|
||||
### グラフィック
|
||||
|
||||
`/docs/img`ディレクトリにグラフィックを保存します。グラフィックを埋め込むには、次の構文を使用します。
|
||||
|
||||
``
|
||||
|
||||
例えば、``は次のように表示されます。
|
||||
|
||||
|
||||
|
||||
### ビデオ
|
||||
|
||||
ビデオはYouTubeに保存されます。アップロード後、埋め込み手順をコピーしてドキュメントに貼り付けることができます。
|
||||
|
||||
コンテンツにYouTubeビデオを埋め込むには、次の手順に従います。
|
||||
|
||||
1. YouTubeにビデオをアップロードします。
|
||||
2. ビデオページの**共有**ボタンをクリックします。
|
||||
3. **埋め込む**をクリックします。
|
||||
4. ポップアップ右下の**コピー**をクリックします。
|
||||
5. コンテンツに`<iframe>`要素を貼り付けます。
|
||||
|
||||
例えば、_Send Checks_ ビデオを埋め込むためのコードは次の通りです。
|
||||
|
||||
```
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/5zRBC7dGSaM?
|
||||
si=Mbi8diaFTDR2fc20" title="YouTube video player" frameborder="0" allow="accelerometer;
|
||||
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
```
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/5zRBC7dGSaM?
|
||||
si=Mbi8diaFTDR2fc20" title="YouTube video player" frameborder="0" allow="accelerometer;
|
||||
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
### テーブル
|
||||
|
||||
Markdocは、テーブルを生成するための3つの異なる構文スタイルを提供します。
|
||||
|
||||
ほとんどの場合、列を区切るためにパイプ文字(|)を使用し、ハイフン3つ以上(---)を使用して列ヘッダを作成します。
|
||||
|
||||
```
|
||||
| | Head 1 |
|
||||
| ------- | ------ |
|
||||
| Label 1 | Val 1 |
|
||||
```
|
||||
|
||||
次のように表示されます。
|
||||
|
||||
| | Head 1 |
|
||||
| ------- | ------ |
|
||||
| Label 1 | Val 1 |
|
||||
|
||||
セルの幅は同じである必要はありません。自動的に列を整列し、必要に応じてテキストを折り返します。
|
||||
|
||||
```
|
||||
| Key | Value |
|
||||
| --- | ----- |
|
||||
| Name | H. G. Wells |
|
||||
| Genre | Science Fiction |
|
||||
| Hyperbole | The greatest story ever told! No one has ever written anything more important than this Victorian era classic. Oh, how swells the heart to ponder the heady philosophies introduced therein! |
|
||||
```
|
||||
|
||||
| Key | Value |
|
||||
| --- | ----- |
|
||||
| Name | H. G. Wells |
|
||||
| Genre | Science Fiction |
|
||||
| Hyperbole | The greatest story ever told! No one has ever written anything more important than this Victorian era classic. Oh, how swells the heart to ponder the heady philosophies introduced therein! |
|
||||
|
||||
ヘッダ行にコロンを使用して、列を左寄せ(:--)、中央寄せ(:-:)、または右寄せ(--:)に配置します。
|
||||
|
||||
```
|
||||
| Model | Color | Price |
|
||||
| :-: | :-- | --: |
|
||||
| Protexra | Electric Blue | 50,000 XRP |
|
||||
| Joatic | Hot Pink | 165,000 XRP |
|
||||
| Zhanu | Neon Green | 234,000 XRP |
|
||||
```
|
||||
|
||||
| Model | Color | Price |
|
||||
| :-: | :-- | --: |
|
||||
| Protexra | Electric Blue | 50,000 XRP |
|
||||
| Joatic | Hot Pink | 165,000 XRP |
|
||||
| Zhanu | Impetuous Green | 1,728,000 XRP |
|
||||
|
||||
左の列はデフォルトで太字になります。左の列に太字のラベルを表示したくない場合は、左の列を空にして、テーブルを1列目から始めてください。
|
||||
|
||||
```
|
||||
| | French | English | German |
|
||||
| --- | --- | --- | --- |
|
||||
| | Fromage | Cheese | Käse |
|
||||
| | Maux d'estomac | Stomach ache | Magenschmerzen |
|
||||
| | Cornichon | Pickle | Essiggurke |
|
||||
```
|
||||
|
||||
| | French | English | German |
|
||||
| --- | --- | --- | --- |
|
||||
| | Fromage | Cheese | Käse |
|
||||
| | Maux d'estomac | Stomach ache | Magenschmerzen |
|
||||
| | Cornichon | Pickle | Essiggurke |
|
||||
|
||||
可能な限り、これらの基本的なテーブルを使用してください。上記の例で提供されていない特別なフォーマットが本当に必要な場合は、HTML構文を使用してテーブルを作成できます。
|
||||
|
||||
### リンク
|
||||
|
||||
リンクは`[<リンクテキスト>](<URL>)`の構文を使用します。
|
||||
|
||||
例えば、次のように書きます。
|
||||
|
||||
`[XRPL.org](http://xrpl.org)で世界のあらゆる問題の解決策をご覧ください。`
|
||||
|
||||
次のように表示されます。
|
||||
|
||||
[XRPL.org](http://xrpl.org)で世界のあらゆる問題の解決策をご覧ください。
|
||||
|
||||
### 共通のリンク
|
||||
|
||||
共通的に引用されるページへのリンクを作成するには、`{% raw-partial file="/docs/_snippets/common-links.md /%}`タグをMarkdownファイルに追加し、`[account_infoメソッド][]`や`[Paymentトランザクション][]`などの参照スタイルのリンクを使用できます。common-linksファイルの内容はアルファベット順になっています。(以前はスクリプトで生成されていましたが、現在は手動で管理されています。)
|
||||
|
||||
### サンプルコード
|
||||
|
||||
サンプルコードを挿入する場合は、バッククォート(`)文字でコードを囲みます。例えば:
|
||||
|
||||
私のお気に入りのメソッドは`nft_info`です。
|
||||
|
||||
次のように表示されます。
|
||||
|
||||
私のお気に入りのメソッドは`nft_info`です。
|
||||
|
||||
長いコードブロックの場合は、言語名に続いて3つのバッククォート(```)を使用します。改行を入力し、サンプルコードを入力します。コードサンプルの最後に改行を入力し、3つのバッククォート(```)でブロックを閉じます。
|
||||
|
||||
例えば、
|
||||
|
||||
```javascript<br/>
|
||||
const prepared = await client.autofill({<br/>
|
||||
"TransactionType": "Payment",<br/>
|
||||
"Account": standby_wallet.address,<br/>
|
||||
"Amount": xrpl.xrpToDrops(sendAmount),<br/>
|
||||
"Destination": standbyDestinationField.value<br/>
|
||||
})
|
||||
```
|
||||
|
||||
次のように表示されます。
|
||||
|
||||
```javascript
|
||||
const prepared = await client.autofill({
|
||||
"TransactionType": "Payment",
|
||||
"Account": standby_wallet.address,
|
||||
"Amount": xrpl.xrpToDrops(sendAmount),
|
||||
"Destination": standbyDestinationField.value
|
||||
})
|
||||
```
|
||||
|
||||
### 部分的なコンテンツ
|
||||
|
||||
頻繁に使用するテキストや、ドキュメント内の複数の場所で定期的に更新が必要なテキストがある場合は、再利用のために_snippetファイルを作成できます。
|
||||
|
||||
`_snippet`ディレクトリにファイルを保存します。部分的なコンテンツを挿入するには、`{% partial file="<file url>" /%}`構文を使用します。
|
||||
|
||||
例えば、次のようなスニペット`/docs/_snippets/secret-key-warning.md`があります。
|
||||
|
||||
<blockquote>
|
||||
{% admonition type="warning" name="Caution" %}<br/>
|
||||
Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.<br/>
|
||||
{% /admonition %}
|
||||
</blockquote>
|
||||
|
||||
テキストを埋め込むには、`{% partial file="/docs/_snippets/secret-key-warning.md" /%}`タグを使用します。
|
||||
|
||||
例えば、
|
||||
|
||||
<blockquote>
|
||||
There I was, happy as a lark, skipping through the daisies, when I shyly handed my secret
|
||||
key to my one true love.
|
||||
|
||||
{% partial file="/docs/_snippets/secret-key-warning.md" /%}
|
||||
|
||||
Alas, if only I had heeded that sage advice, I would not rue the day as I do today.
|
||||
</blockquote>
|
||||
|
||||
次のように表示されます。
|
||||
|
||||
<blockquote>
|
||||
There I was, happy as a lark, skipping through the daisies, when I shyly handed my secret key to my one true love.
|
||||
|
||||
{% partial file="/docs/_snippets/secret-key-warning.md" /%}
|
||||
|
||||
Alas, if only I had heeded that sage advice, I would not rue the day as I do today.
|
||||
</blockquote>
|
||||
|
||||
|
||||
{% child-pages /%}
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
html: tutorial-guidelines.html
|
||||
parent: contribute-documentation.html
|
||||
seo:
|
||||
description: このサイトのチュートリアルの構成と、質の高いチュートリアルを投稿するためのガイドラインを学びましょう。
|
||||
---
|
||||
# チュートリアルガイドライン
|
||||
|
||||
私たちは、開発者がXRP Ledger上でのトランザクションやリクエストの仕組みを学ぶことができる、モジュール式のチュートリアルフレームワークを作成しています。開発者は、ビジネスソリューションについて学ぶためにモジュールを確認し、自身のアプリケーションでスクリプトを再利用することができます。
|
||||
|
||||
|
||||
# 根拠
|
||||
|
||||
開発者は次の2つのことを求めています。
|
||||
|
||||
1. 自分のアプリケーションにコピー＆ペーストできるコードのサンプル。
|
||||
2. 完全なAPIリファレンスのドキュメント。
|
||||
|
||||
コンセプトに関する情報は最小限としチュートリアルを完了するために必要な情報のみとしてください。背景やより深い理解のために、必要であれば、チュートリアルの最後にコンセプトに関するトピックへのリンクを提供してください。
|
||||
|
||||
チュートリアルプログラムは、マルコム・ノウルズが提唱する、社会人の学習を支援するための6つの前提に沿って構成されています。
|
||||
|
||||
1. 大人は、なぜ何かを学ぶ必要があるのかを知る必要があります。
|
||||
2. 大人は、経験を積み重ねる必要があります。
|
||||
3. 大人は、自分の学習に責任を感じる必要があります。
|
||||
4. 大人は、トレーニングが当面の問題を解決してくれるなら、学ぶ準備が整っています。
|
||||
5. 大人は、トレーニングが問題に焦点を当てたものであることを望みます。
|
||||
6. 大人は、動機づけが内発的にもたらされるときに最もよく学びます。
|
||||
|
||||
さらに、ラルフ・スメドレーの「人は楽しいときに最もよく学ぶ」という言葉も付け加えておきましょう。軽い気持ちで学ぶと、学習者をリラックスさせることができ、教材が抵抗なく頭に入ってくるのです。
|
||||
|
||||
|
||||
# サンプルコード vs タスク vs コンセプト vs チュートリアル
|
||||
|
||||
これまで、異なるタイプのドキュメントが _チュートリアル_ として表示されたり、境界線が曖昧なことがありました。ここでは、その違いを定義するのに役立ついくつかの比較を紹介します。
|
||||
|
||||
|
||||
## サンプルコード
|
||||
|
||||
サンプルコードとは、APIの機能を実装するためのベストプラクティスを示す、適切にコメントされたスニペットやアプリケーションのことです。サンプルコードはモジュール化されており、カスタマイズをほとんど必要とせず、再利用可能です。
|
||||
|
||||
サンプルコードは理想的です。なぜなら、上級者は通常、正式なチュートリアルがなくても、サンプルをスキャンしてすぐに使うことができるからです。また、他の人がチュートリアルの基礎として使うこともできます。サンプルコードの開発者は、自分の得意なことに集中することができ、テクニカルライターやサポート担当者は、サンプルを使って質の高いトレーニング資料を作成することができます。
|
||||
|
||||
|
||||
## タスク
|
||||
|
||||
タスクは、特定の目的を達成するためのステップバイステップの指示です。例えば、"Red Hat Linux Serverにrippledをインストールする"などです。タスクドキュメントはあまり教育的なものではありません。実装ごとに一度だけ実行されるタスクや、常におなじみのパターンに従うメンテナンスタスクが頻繁に記述されています。タスクはトラブルシューティングのガイダンスを示します。
|
||||
|
||||
|
||||
## コンセプト
|
||||
|
||||
コンセプトでは、API の要素やそれらがどのように動作するか、どのような場合にそれらを使用するかについて説明します。もしチュートリアルがプログラミングのタスクの前や途中に長い説明を必要とする場合、説明を新しいトピックに分けるか、既存のトピックにリンクして適切なコンテキストを設定する方法を検討してください。
|
||||
|
||||
例えば、3段落のコンテキストと1行のコードは、チュートリアルではなく、コンセプトとして扱うべきでしょう。
|
||||
|
||||
|
||||
## チュートリアル
|
||||
|
||||
チュートリアルは、機能を実装するためのベストプラクティスを示すサンプルコードから始まります。チュートリアルでは、コードの各ブロックの目的を説明しながら、開発のプロセスを段階的に進めていきます。
|
||||
|
||||
チュートリアルではさらに、ビジネス上の問題を解決するために、いくつかの機能を組み合わせます。チュートリアルでは、あるタスクを完了するための簡単な手順を説明します。そして、開発者がいくつかの異なるシナリオを試せるように修正を提案するかもしれません。チュートリアルは、ある限られた範囲の動作に焦点を当てているため、広範なトラブルシューティング情報を必要としないようにすべきです。
|
||||
|
||||
|
||||
## ユースケース
|
||||
|
||||
ユースケースでは、複数の機能を組み合わせて、ビジネス上の問題を解決する実用的なアプリケーションを作成する方法を説明します。ユースケースは、コンテキストを提供し、意思決定プロセスを支援し、実装の各ステップに適切なトピックへのリンクを提供します。
|
||||
|
||||
|
||||
# チュートリアルの構成要素
|
||||
|
||||
このセクションでは、XRPL.orgで使用されているチュートリアルモジュールの要素について説明します。
|
||||
|
||||
|
||||
## サンプルアプリケーション
|
||||
|
||||
XRPLチュートリアルのサンプルコードはモジュール式になっています。例えば、スクリプト1はテストアカウントの作成方法、XRP Ledgerへのアクセス方法、アカウント間でのXRP送金方法を示しています。それ以降のサンプルはスクリプト1の機能を再利用することができます。
|
||||
|
||||
ビジネス上の問題に対する実用的な解決策を示すために必要な、特定の最小限の関数コードを持つ新しいスクリプトを作成してください。サンプルは、ビジネスプロセスを説明するのに十分な動作を持つ逐次的なものでなければなりません。
|
||||
|
||||
たとえば、最初のNFTチュートリアルでは、NFTのミント、取得、バーンの方法を示します。次のチュートリアルでは、売りオファーの作成と受け入れ、買いオファーの作成と受け入れの方法を示します。
|
||||
|
||||
アプリケーションのUXは、トピックに関連するものでない限り、過度に重視しないでください。すべてのチュートリアルで、標準的な外観と操作感のCSSファイルを使用してください。
|
||||
|
||||
可能な限り、他のモジュールのコードを再利用してください。以前のモジュールの動作を変更する必要がある場合があります。関数名をオーバーロードするか、モジュールを修正して別の名前で保存してください。
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
html: tutorial-structure.html
|
||||
parent: contribute-documentation.html
|
||||
seo:
|
||||
description: 一般的なチュートリアルの構成要素の要約です。
|
||||
---
|
||||
# チュートリアルの構成
|
||||
|
||||
各XRP Ledgerチュートリアルは、同一のフォーマットで構成されています。
|
||||
|
||||
1. チュートリアルで説明する機能の簡単な説明。
|
||||
2. コードを実行するための前提条件(必要な場合)、またはサンプルコードへのリンク。
|
||||
3. チュートリアルの機能の使用例。
|
||||
4. サンプルコードの解説と、そのスクリプトの特徴的な要素の紹介。
|
||||
5. 次のステップとして試すべき概念的な情報や優れたチュートリアルへのリンク。
|
||||
|
||||
セットアップ(前提条件)と使用方法とコード開発は分けて考えましょう。これらはそれぞれ異なる活動であり、それぞれ脳の異なる領域を動かします。この3つの要素を一度に考えようとすると、混乱につながります。
|
||||
|
||||
## 説明
|
||||
|
||||
|
||||
|
||||
そのサンプルが何を示しているかを記載してください。可能であれば、各サンプルには関連する特定のタスクを達成するための手順を記述してください。(NFTの売却オファーの作成、売却オファーの受け入れ、売却オファーの削除など)。チュートリアルで説明されている内容を理解するのに十分なコンセプトに関する情報を記載し、必要であれば、追加情報へのリンクも記載します。
|
||||
|
||||
## 前提条件
|
||||
|
||||
|
||||
|
||||
必要なソフトウェアと、チュートリアルを実行するために必要なすべてのサンプルコードへのリンクを提供します。必要であれば、サードパーティのツールの使い方を簡単に説明しますが、ユーザが自由に深く掘り下げることができるように、ソースとなるウェブサイトへのリンクを提供します。
|
||||
|
||||
## 使用例
|
||||
|
||||
|
||||
|
||||
チュートリアルのアプリケーションの完成した動作例を提供することから始めましょう。これは、ソフトウェアを使って問題を解決するチャンスです。
|
||||
|
||||
チュートリアルの各ステップにはスクリーンショットを使用してください。これによって、ユーザは自分でコードを実行しなくてもチュートリアルを理解することができます。もちろん、コードを実行することが _望ましい_ ですが、これにりユーザに選択肢を与えることができます。
|
||||
|
||||
適切な条件におけるシナリオを記述してください。インターネットへの接続が途切れなければ、アプリケーションは問題なく動作するはずです。チュートリアルに関連しないトラブルシューティングの情報を提供しないでください。
|
||||
|
||||
## コード解説
|
||||
|
||||
|
||||
|
||||
コードを1ブロックずつ見ていきましょう。既に説明したトピックを繰り返さないでください。サンプルコードには、HTML構文のような基本的な部分のプログラミング方法については、その実装に独自なものがない限り、詳細な説明はしないでください。
|
||||
|
||||
強調すべき重要なことは、XRPLとのやりとりはすべてトランザクションかリクエストであり、すべてのトランザクションとリクエストは本質的に同じであるということです。私たちが提供するサンプルコードは、トランザクションやリクエストを準備する方法と、返された結果を処理する方法を示しています。1つのトランザクションやリクエストをどのように送信しどのようなレスポンスを返すかを知ることは、他のトランザクションやリクエストの処理について非常に良いヒントとなります。
|
||||
|
||||
(技術的には、リクエストに似た第3のカテゴリがあります。[Subscriptionメソッド](../../docs/references/http-websocket-apis/public-api-methods/subscription-methods/index.md)をご覧ください)。
|
||||
|
||||
## 関連項目
|
||||
|
||||
|
||||
|
||||
チュートリアルの最後には、追加の資料、概念的な情報、学習のにおいて有益な次のステップとなるチュートリアルへのリンクを提供します。
|
||||
Reference in New Issue
Block a user