From 66bf9aed5c1ba376f30690994303e3f602a38db8 Mon Sep 17 00:00:00 2001 From: tequ Date: Wed, 23 Aug 2023 17:22:11 +0900 Subject: [PATCH] [JA] translate contributing contents --- content/contributing/report-a-scam.ja.md | 30 ++ .../contribute-code/contribute-code.ja.md | 94 +++++ .../create-custom-transactors.ja.md | 389 ++++++++++++++++++ .../contribute-documentation.ja.md | 168 ++++++++ .../creating-diagrams.ja.md | 33 ++ .../documentation-translations.ja.md | 74 ++++ .../documentation-translations.md | 2 +- .../tutorial-guidelines.ja.md | 83 ++++ .../tutorial-guidelines.md | 4 +- .../tutorial-structure.ja.md | 54 +++ dactyl-config.yml | 38 +- 11 files changed, 957 insertions(+), 12 deletions(-) create mode 100644 content/contributing/report-a-scam.ja.md create mode 100644 content/resources/contribute-code/contribute-code.ja.md create mode 100644 content/resources/contribute-code/create-custom-transactors.ja.md create mode 100644 content/resources/contribute-documentation/contribute-documentation.ja.md create mode 100644 content/resources/contribute-documentation/creating-diagrams.ja.md create mode 100644 content/resources/contribute-documentation/documentation-translations.ja.md create mode 100644 content/resources/contribute-documentation/tutorial-guidelines.ja.md create mode 100644 content/resources/contribute-documentation/tutorial-structure.ja.md diff --git a/content/contributing/report-a-scam.ja.md b/content/contributing/report-a-scam.ja.md new file mode 100644 index 00000000000..a8267d3edc4 --- /dev/null +++ b/content/contributing/report-a-scam.ja.md @@ -0,0 +1,30 @@ +--- +html: report-a-scam.html +parent: contribute.html +--- +# 詐欺の報告 +発展する業界において、信頼とセキュリティは非常に重要ですが、詐欺はクリプトとブロックチェーンの進歩を妨げ続けています。Xrplorer forensicsチームのようなXRP Ledgerコミュニティ全体の個人やチームは、詐欺を報告するための無料ツールを提供することで、これらの詐欺行為を抑制する手助けをしています。 + +## 報告する +詐欺に遭ったと思ったら、詐欺の手口や詐欺業者について、できるだけ早く、できるだけ多くの情報を集めるようにしてください。どのように行動すべきかは以下の方法を確認してください。 + +**注意:** 誰もXRP Ledgerのアカウントを凍結したり、トランザクションを元に戻したりすることはできません。これはXRP Ledgerブロックチェーンの分散型設計によるものです。 + +1. [Xrplorerの調査チーム](https://xrplorer.com/forensics/submit)に詐欺業者のウォレットアドレスを提出してください。 + + これにより、不正行為に使用されたアカウントにフラグを立て、他のユーザ、ウォレット、および取引所に対する追加の監視、自動追跡、および警告に含めることができます。 + +2. 最寄りの警察署に通報してください。詐欺業者が捕まれば、お金を取り戻せる場合があります。 + +3. 詐欺業者が取引所にXRPを送金した場合は、必ず取引所のサポートチームに連絡してください。取引所は詐欺業者の口座を凍結することができます。以下は、いくつかの有名な取引所のサポートリンクです。 + + - [Binance](https://www.binance.com/en/support) + - [Coinbase](https://help.coinbase.com/) + - [Uphold](https://support.uphold.com/hc/en-us/requests/new) + - [Bitrue](https://www.bitrue.com/exchange-web/footer/contactus.html) + +4. 詐欺業者がXRP Ledger上でXRPを他のトークンと交換した場合、そのトークンの発行者に連絡してください。発行者は[詐欺業者のトラストラインを凍結する](freeze-a-trust-line.html)ことができるかもしれません。 + +詐欺業者の報告に関する詳細は、[Xrplorer Forensicsのヘルプ](https://xrplorer.com/forensics/help)をご覧ください。 + +XRP Ledgerコミュニティからのヘルプについては、[XRPChatフォーラム](https://xrpchat.com)を利用することもできます。 diff --git a/content/resources/contribute-code/contribute-code.ja.md b/content/resources/contribute-code/contribute-code.ja.md new file mode 100644 index 00000000000..411396746b0 --- /dev/null +++ b/content/resources/contribute-code/contribute-code.ja.md @@ -0,0 +1,94 @@ +--- +html: contribute-code.html +parent: resources.html +blurb: Learn how features can be coded into the XRP Ledger protocol. +labels: + - ブロックチェーン +--- +# コードへの貢献 + +XRP Ledgerを動かすソフトウェアはオープンソースです。誰でもダウンロードし、変更し、拡張し、調査することができます。もしあなたがコードに貢献したいのであれば、コミュニティと協力してあなたの変更の仕様を定義し、XRP Ledgerのプロトコルとブロックチェーンの一部になる前にコードをテストすることが重要です。 + +# コアサーバのソースコード + +XRP Ledgerを動かすソフトウェアはオープンソースです。コミュニティが参加することで、より良いものが生まれます。[ドキュメント](docs.html)内の"[Source]"リンクから関連するソースコードに直接ジャンプしたり、GitHubでソースコードを閲覧することができます： + +| XRP Ledger ソースコード | | +|:-----------------------|:----------------------------------------------------| +| リポジトリ | | +| ライセンス | [Multiple; ISC (permissive)](https://github.com/XRPLF/rippled/blob/develop/LICENSE.md) | +| プログラム言語 | C++ | + +何から始めたらいいか分からないという方のために、Dev Null Productionsは、XRP Ledgerサーバー(`rippled`)のコア実装の仕組みや機能を説明した、詳細かつ充実した[**ソースコード・ガイド**](https://xrpintel.com/source)を提供しています。 + + +## XRP Ledgerの規格 + +`rippled`に対する変更はXRP Ledger Standard (XLS)、つまり変更の仕様を特定し詳細に記述した文書によって管理されます。開発にコミットする前に、[XRPL-Standardsリポジトリ](https://github.com/XRPLF/XRPL-Standards/discussions)で議論を始める必要があります。これにより、コミュニティはあなたの変更に関して議論し、フィードバックを提供する機会を得ることができます。 + +**注記:*** バグ修正にはXLSは必要ありませんが、Amendmentが必要になる場合があります。 + +XLSの作成には独自のプロセスがありますが、簡単にまとめると次のようになります： + +1. ディスカッションを開始し、フィードバックを集めます。 +2. StandardリポジトリにXLSドラフトを作成します。 +3. XLSドラフトを仕様候補として公開します。 + +詳細については、[XLS貢献ガイド](https://github.com/XRPLF/XRPL-Standards/blob/master/CONTRIBUTING.md) をご覧ください。 + + +## Amendmentの実装 + +XLSドラフトを作成した後、その変更にAmendmentが必要かどうかを判断する必要があります。特に次のような**トランザクション処理**に影響する変更にはAmendment が必要です。 + +- レジャールールを変更し、異なる結果をもたらすもの。 +- トランザクションの追加または削除。 +- コンセンサスへの影響がある変更。 + +**注記:** 変更にAmendmentが必要ない場合、そのままコーディングとデプロイに進むことができます。 + +コードをAmendmentとして実装するには、次のファイルにAmendment情報を追加する必要があります。 + +- **Feature.cpp**: + + 開発が完了するまで、`Supported`パラメータは`no`に設定してください。 + + バグの修正の場合、`DefaultVote`パラメータを`yes`に設定する必要があります。 + +- **Feature.h**: `numFeatures` カウンタを増やし、`extern uint256 const` 変数を宣言します。 + + +## コーディングとデプロイ + +一般的な開発プロセスは以下の通りです。 + +1. コードを開発するためにはまず、[`rippled` リポジトリ](https://github.com/XRPLF/rippled) をフォークまたはブランチを作成します。 + + **ヒント:** 何から始めたらいいかわからない場合は、_Dev Null Productions_ が詳細かつ充実した [`rippled` ソースコードガイド](https://xrpintel.com/source) を提供しています。 + +2. 単体テストと統合テストを実行します。独立した環境で作業をテストするにはスタンドアロンモードでサーバを実行するのが良いでしょう。 + +3. `XRPLF:develop`にプルリクエストを作成します。 + + **Amendment向けの注記:** **Feature.cpp**の`Supported`パラメータを`yes`に更新します。 + +4. プルリクエストがXRP Ledgerのメンテナによって承認されると、あなたのコードは`develop`にマージされ、Devnet上で追加のテストを行うことができます。 + + **Amendment向けの注記:** + - `DefaultVote`パラメータはロックされます。 + - もしAmendmentに問題が見つかれば、Amendmentの修正と新しいPRの提出を再度行う必要があります。新しいPRでは`DefaultVote`を変更することができます。 + +年に4回、`develop`で承認されたPRからリリース候補がビルドされます。このパッケージはTestnetとMainnet上のいくつかのノードにデプロイされます。リリース候補に問題がなければ、コードは`master`にマージされ、メインネット上のノードはこのビルドにアップグレードできます。 + +6. 新しいAmendmentは合意形成プロセスを経て、バリデーターがそのAmendmentを有効にするかどうかを投票します。 + + +## コードのフローチャート + +![コードのフローチャート](img/Contribute Code Flowchart.png) + + +## 関連項目 + +- **コンセプト:** + - [Amendment](amendments.html) diff --git a/content/resources/contribute-code/create-custom-transactors.ja.md b/content/resources/contribute-code/create-custom-transactors.ja.md new file mode 100644 index 00000000000..167cbba8cef --- /dev/null +++ b/content/resources/contribute-code/create-custom-transactors.ja.md @@ -0,0 +1,389 @@ +--- +html: create-custom-transactors.html +parent: contribute-code.html +blurb: XRPレジャーとやり取りするためのカスタムトランザクタを作成します。 +labels: + - 開発 + - ブロックチェーン +--- +# カスタムトランザクタの作成 + +_トランザクタ_ はトランザクションを処理し、XRP Ledgerを変更するコードです。カスタムトランザクタを作成することで、`rippled`に新しい機能を追加することができます。このチュートリアルではトランザクタのコーディングについて説明しますが、それをXRPLに追加するにはAmendmentプロセスを経る必要があります。 [XRPレジャーのコードへの貢献](contribute-code-flow.html)をご覧ください。 + +トランザクタは 基本的な処理順序に則って処理されます。 + +1. シリアライズ型レジャーエントリ(SLE/serialized type ledger entry)の _view_ へアクセスします。 +2. _view_ 内の値を更新、削除、挿入します。 +3. 確定した変更を _view_ からレジャーに適用します。 + +**注記:** _view_ はレジャーのサンドボックスです。トランザクタは必要なエラーチェックと変更のすべてをサンドボックス内で行い、レジャーでは直接行いません。値が確定した後、変更はレジャーにアトミックに適用されます。 + +このチュートリアルでは、既存の`CreateCheck`トランザクションを例として使用します。ソースファイルはここで確認できます。 + +- [ヘッダファイル](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.h) +- [CPPファイル](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.cpp) + + +## ヘッダファイル + +次の形式でヘッダーファイルを作成します。 + +```c++ +namespace ripple { + +class CreateCheck : public Transactor +{ +public: + static constexpr ConsequencesFactoryType ConsequencesFactory{Normal}; + + explicit CreateCheck(ApplyContext& ctx) : Transactor(ctx) + { + } + + static NotTEC + preflight(PreflightContext const& ctx); + + static TER + preclaim(PreclaimContext const& ctx); + + TER + doApply() override; +}; + +} // namespace ripple +``` + +`ApplyContext`でトランザクタを初期化すると、トランザクタは以下にアクセスできます： + +- トランザクタをトリガーしたトランザクション。 +- SLEのビュー。 +- エラーを記録するためのジャーナル。 + + +## CPPファイル + +### 1. `preflight`関数の追加 + +`preflight`関数はレジャーにアクセスする前にトランザクション自体にエラーがないかチェックします。無効なトランザクションや正しく設定されていないトランザクションは拒否されなければなりません。 + +- `PreflightContext`はレジャーのビューを持っていません。 +- レジャーやトランザクションからフィールドを取得するには、次のようにブラケット記法を使用します。 + + auto const curExpiration = (*sle*)[~sfExpiration]; + (*sle)[sfBalance] = (*sle)[sfBalance] + reqDelta; + + **注記:** `~`記号は optional型を返します。 + +- レジャーとトランザクションのスキーマはこちらから確認できます。 + - [`LedgerFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp) + - [`TxFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp) + +-` rippled` はトランザクションの結果を結果コードで表します。[トランザクションの結果](transaction-results.html)をご覧ください。 + +```c++ +CreateCheck::preflight(PreflightContext const& ctx) +{ + // Check if this amendment functionality is enabled on the network. + if (!ctx.rules.enabled(featureChecks)) + return temDISABLED; + + NotTEC const ret{preflight1(ctx)}; + if (!isTesSuccess(ret)) + return ret; + + if (ctx.tx.getFlags() & tfUniversalMask) + { + // There are no flags (other than universal) for CreateCheck yet. + JLOG(ctx.j.warn()) << "Malformed transaction: Invalid flags set."; + return temINVALID_FLAG; + } + if (ctx.tx[sfAccount] == ctx.tx[sfDestination]) + { + // They wrote a check to themselves. + JLOG(ctx.j.warn()) << "Malformed transaction: Check to self."; + return temREDUNDANT; + } + + { + STAmount const sendMax{ctx.tx.getFieldAmount(sfSendMax)}; + if (!isLegalNet(sendMax) || sendMax.signum() <= 0) + { + JLOG(ctx.j.warn()) << "Malformed transaction: bad sendMax amount: " + << sendMax.getFullText(); + return temBAD_AMOUNT; + } + + if (badCurrency() == sendMax.getCurrency()) + { + JLOG(ctx.j.warn()) << "Malformed transaction: Bad currency."; + return temBAD_CURRENCY; + } + } + + if (auto const optExpiry = ctx.tx[~sfExpiration]) + { + if (*optExpiry == 0) + { + JLOG(ctx.j.warn()) << "Malformed transaction: bad expiration"; + return temBAD_EXPIRATION; + } + } + + return preflight2(ctx); +} +``` + + +### 2. `preclaim`関数の追加 + +`preclaim`関数は、現在のレジャーの情報を見る必要があるエラーをチェックします。 + +- このステップが結果コード`tesSUCCESS`または`tec`を返した場合、トランザクションはキューに入れられ、ピアに送信されます。 + +```c++ +CreateCheck::preclaim(PreclaimContext const& ctx) +{ + AccountID const dstId{ctx.tx[sfDestination]}; + + // Use the `keylet` function to get the key of the SLE. Views have either `read` or `peek` access. + // `peek` access allows the developer to modify the SLE returned. + auto const sleDst = ctx.view.read(keylet::account(dstId)); + if (!sleDst) + { + JLOG(ctx.j.warn()) << "Destination account does not exist."; + return tecNO_DST; + } + + auto const flags = sleDst->getFlags(); + + // Check if the destination has disallowed incoming checks + if (ctx.view.rules().enabled(featureDisallowIncoming) && + (flags & lsfDisallowIncomingCheck)) + return tecNO_PERMISSION; + + if ((flags & lsfRequireDestTag) && !ctx.tx.isFieldPresent(sfDestinationTag)) + { + // The tag is basically account-specific information we don't + // understand, but we can require someone to fill it in. + JLOG(ctx.j.warn()) << "Malformed transaction: DestinationTag required."; + return tecDST_TAG_NEEDED; + } + + { + STAmount const sendMax{ctx.tx[sfSendMax]}; + if (!sendMax.native()) + { + // The currency may not be globally frozen + AccountID const& issuerId{sendMax.getIssuer()}; + if (isGlobalFrozen(ctx.view, issuerId)) + { + JLOG(ctx.j.warn()) << "Creating a check for frozen asset"; + return tecFROZEN; + } + // If this account has a trustline for the currency, that + // trustline may not be frozen. + // + // Note that we DO allow create check for a currency that the + // account does not yet have a trustline to. + AccountID const srcId{ctx.tx.getAccountID(sfAccount)}; + if (issuerId != srcId) + { + // Check if the issuer froze the line + auto const sleTrust = ctx.view.read( + keylet::line(srcId, issuerId, sendMax.getCurrency())); + if (sleTrust && + sleTrust->isFlag( + (issuerId > srcId) ? lsfHighFreeze : lsfLowFreeze)) + { + JLOG(ctx.j.warn()) + << "Creating a check for frozen trustline."; + return tecFROZEN; + } + } + if (issuerId != dstId) + { + // Check if dst froze the line. + auto const sleTrust = ctx.view.read( + keylet::line(issuerId, dstId, sendMax.getCurrency())); + if (sleTrust && + sleTrust->isFlag( + (dstId > issuerId) ? lsfHighFreeze : lsfLowFreeze)) + { + JLOG(ctx.j.warn()) + << "Creating a check for destination frozen trustline."; + return tecFROZEN; + } + } + } + } + if (hasExpired(ctx.view, ctx.tx[~sfExpiration])) + { + JLOG(ctx.j.warn()) << "Creating a check that has already expired."; + return tecEXPIRED; + } + return tesSUCCESS; +} +``` + + +### 3. Add a `doApply()` function. + +The `doApply()` function has read/write access, enabling you to modify the ledger. + +```c++ +CreateCheck::doApply() +{ + auto const sle = view().peek(keylet::account(account_)); + if (!sle) + return tefINTERNAL; + + // A check counts against the reserve of the issuing account, but we + // check the starting balance because we want to allow dipping into the + // reserve to pay fees. + { + STAmount const reserve{ + view().fees().accountReserve(sle->getFieldU32(sfOwnerCount) + 1)}; + + if (mPriorBalance < reserve) + return tecINSUFFICIENT_RESERVE; + } + + // Note that we use the value from the sequence or ticket as the + // Check sequence. For more explanation see comments in SeqProxy.h. + std::uint32_t const seq = ctx_.tx.getSeqProxy().value(); + Keylet const checkKeylet = keylet::check(account_, seq); + auto sleCheck = std::make_shared(checkKeylet); + + sleCheck->setAccountID(sfAccount, account_); + AccountID const dstAccountId = ctx_.tx[sfDestination]; + sleCheck->setAccountID(sfDestination, dstAccountId); + sleCheck->setFieldU32(sfSequence, seq); + sleCheck->setFieldAmount(sfSendMax, ctx_.tx[sfSendMax]); + if (auto const srcTag = ctx_.tx[~sfSourceTag]) + sleCheck->setFieldU32(sfSourceTag, *srcTag); + if (auto const dstTag = ctx_.tx[~sfDestinationTag]) + sleCheck->setFieldU32(sfDestinationTag, *dstTag); + if (auto const invoiceId = ctx_.tx[~sfInvoiceID]) + sleCheck->setFieldH256(sfInvoiceID, *invoiceId); + if (auto const expiry = ctx_.tx[~sfExpiration]) + sleCheck->setFieldU32(sfExpiration, *expiry); + + view().insert(sleCheck); + + auto viewJ = ctx_.app.journal("View"); + // If it's not a self-send (and it shouldn't be), add Check to the + // destination's owner directory. + if (dstAccountId != account_) + { + auto const page = view().dirInsert( + keylet::ownerDir(dstAccountId), + checkKeylet, + describeOwnerDir(dstAccountId)); + + JLOG(j_.trace()) << "Adding Check to destination directory " + << to_string(checkKeylet.key) << ": " + << (page ? "success" : "failure"); + + if (!page) + return tecDIR_FULL; + + sleCheck->setFieldU64(sfDestinationNode, *page); + } + + { + auto const page = view().dirInsert( + keylet::ownerDir(account_), + checkKeylet, + describeOwnerDir(account_)); + + JLOG(j_.trace()) << "Adding Check to owner directory " + << to_string(checkKeylet.key) << ": " + << (page ? "success" : "failure"); + + if (!page) + return tecDIR_FULL; + + sleCheck->setFieldU64(sfOwnerNode, *page); + } + // If we succeeded, the new entry counts against the creator's reserve. + adjustOwnerCount(view(), sle, 1, viewJ); + return tesSUCCESS; +} +``` + + +## 追加の関数 + +必要に応じて、カスタムトランザクタにヘルパー関数を追加することができます。特殊な場合に役立つ特別な関数がいくつかあります。 + + +### `calculateBaseFee` + +ほとんどのトランザクションはデフォルトの[Referenceトランザクションコスト](transaction-cost.html)をそのまま引き継ぎます。しかし、トランザクションで通常以外のトランザクションコストを定義する必要がある場合、トランザクションの`calculateBaseFee`メソッドをカスタムメソッドに置き換えることができます。 + +次の例では、`EscrowFinish`ランザクションが条件付きエスクローに対して、フルフィルメントの大きさに応じて追加コストを請求する方法を示しています。 + +```c++ +XRPAmount +EscrowFinish::calculateBaseFee(ReadView const& view, STTx const& tx) +{ + XRPAmount extraFee{0}; + + if (auto const fb = tx[~sfFulfillment]) + { + extraFee += view.fees().base * (32 + (fb->size() / 16)); + } + + return Transactor::calculateBaseFee(view, tx) + extraFee; +} +``` + + +### `makeTxConsequences` + +`rippled`は[`TxConsequences`](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/applySteps.h#L41-L44)クラスを使用して、トランザクション適用時のアカウントへの結果を記述します。このクラスは手数料、使用可能な最大XRP、トランザクションによって消費されたシーケンス番号の数を追跡します。結果には次の3つのタイプがあります。 + +- **ノーマル:**トランザクションは署名に影響を与えず、XRP手数料を消費するのみです。手数料を超えてXRPを消費するトランザクションは正常とはみなされません。 +- **ブロッカー:**トランザクションの署名に影響を与え、有効なトランザクションがその後ろにキューイングされるのを防ぎます。 +- **カスタム:**トランザクタは結果を決定するために追加の作業を行う必要があります。 + +`makeTxConsequences`関数を使うと、以下のような状況に対してカスタム結果を作成することができます： + +- XRPを送信する支払い。 +- 複数のシーケンス番号を消費するチケット。 +- 設定されたフラグやフィールドによって、正常またはブロッカーとなるトランザクション。 + +**注記:** `TxConsequences`は[トランザクションキュー](transaction-queue.html)にのみ影響します。トランザクションがレジャーに適用されたときに手数料を請求する可能性が高い場合、それはピアに送信されます。手数料を請求する可能性がない場合、またはそれが判断できない場合は、送信されません。 + + +```c++ +SetAccount::makeTxConsequences(PreflightContext const& ctx) +{ + // The SetAccount may be a blocker, but only if it sets or clears + // specific account flags. + auto getTxConsequencesCategory = [](STTx const& tx) { + if (std::uint32_t const uTxFlags = tx.getFlags(); + uTxFlags & (tfRequireAuth | tfOptionalAuth)) + return TxConsequences::blocker; + + if (auto const uSetFlag = tx[~sfSetFlag]; uSetFlag && + (*uSetFlag == asfRequireAuth || *uSetFlag == asfDisableMaster || + *uSetFlag == asfAccountTxnID)) + return TxConsequences::blocker; + + if (auto const uClearFlag = tx[~sfClearFlag]; uClearFlag && + (*uClearFlag == asfRequireAuth || *uClearFlag == asfDisableMaster || + *uClearFlag == asfAccountTxnID)) + return TxConsequences::blocker; + + return TxConsequences::normal; + }; + + return TxConsequences{ctx.tx, getTxConsequencesCategory(ctx.tx)}; +} +``` + + +## 次のステップ + +新しいトランザクタでサーバを再コンパイルし、[スタンドアロンモード](use-stand-alone-mode.html)でテストしてください。もしAmendmentの後ろにトランザクタをコーディングした場合、設定ファイルを使ってその機能を[強制的に有効にする](test-amendments.html)ことができます。 diff --git a/content/resources/contribute-documentation/contribute-documentation.ja.md b/content/resources/contribute-documentation/contribute-documentation.ja.md new file mode 100644 index 00000000000..d123834df45 --- /dev/null +++ b/content/resources/contribute-documentation/contribute-documentation.ja.md @@ -0,0 +1,168 @@ +--- +html: contributing-to-documentation.html +parent: docs.html +blurb: XRP Ledgerドキュメントのコントリビューションガイドです。 +--- +# ドキュメントへの貢献 + +XRP Ledger開発者ポータルへの貢献を検討いただきありがとうございます！ + + +私たちは、あなたが興味を持ってくださっていることにとても感動しています。XRP Ledger(XRPL)へ貢献することは、XRPLついて学ぶ素晴らしい機会です。 + +私たちはあなたのプルリクエストを喜んでレビューします。プロセスをできるだけ円滑に進めるため、このドキュメントを読み、記載されているガイドラインに従ってください。 + +## 当サイトについて + +XRPL Dev Portalでは、開発者が開発を開始するためのサンプルコードやその他の情報を含む、XRP Ledgerの包括的なドキュメントを提供しています。 + +本プロジェクトの公式リポジトリはとなっています。投稿の著作権はそれぞれの投稿者に帰属しますが、MIT[ライセンス](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE)の下で提供されなければなりません。 + + + +## リポジトリの構成 + +- [assets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/assets) - サイトのテンプレートで使用される静的ファイル。 +- [content/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content) - ドキュメントを構築するために使用されるソースファイル。ほとんどがMarkdownです。 + - [content/\_code-samples/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples) - ドキュメントで使用または参照されているコードサンプル。可能な限り、これらは完全に機能する/実行可能なスクリプトです。 + - [content/\_img-sources/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_img-sources) - ドキュメントで使用されている画像の元ファイル。`.uxf`ファイルは[Umlet](https://www.umlet.com/)で作成されたダイアグラムです。 + - [content/\_snippets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_snippets) - Dactylプリプロセッサを使用して、他のコンテンツファイルに挿入される再利用可能なMarkdownテキストの断片。 +- [img/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) - ドキュメントコンテンツで使用される画像。 +- [template/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/template) - HTMLを構築するためのテンプレートファイル。 +- [tool/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/tool) - フィルター、スタイルチェッカー・ルール等のスクリプト。 +- [styles/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/styles) - assetsフォルダにCSSファイルを生成するための元ファイル(SCSS)。 +- [`dactyl-config.yml`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/dactyl-config.yml) - サイトのメタデータを含むメイン設定ファイル。設定ファイルのフォーマットについては、[設定フォーマット](#設定ファイルのフォーマット)を参照してください。 + +## プルリクエストが承認されるための条件 + +レビューやマージが承認される前に、それぞれのプルリクエストは以下の条件を満たしていなければなりません。 +- インテグレーションテストに合格すること。 +- レビューの準備が整うまで、[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)を遵守してください。 + +## Dactylのセットアップ + +ポータルは[Dactyl](https://github.com/ripple/dactyl)を使用して構築されています。 + +Dactylには[Python 3](https://python.org/)が必要です。[pip](https://pip.pypa.io/en/stable/)を使ってインストールしてください： + +``` +pip3 install dactyl +``` + +## サイトの構築 + +このリポジトリでは、[**Dactyl**](https://github.com/ripple/dactyl)を使用して、すべてのドキュメントのHTMLをビルドしています。[Dactylのセットアップ](#dactylのセットアップ)を行った後、プロジェクトのルートディレクトリからサイトをビルドすることができます。 + +``` +dactyl_build +``` + +生成されたコンテンツは`out/`ディレクトリに出力されます。これらのコンテンツはウェブブラウザでファイルとして開いたり、ウェブサーバで静的コンテンツとして扱うことができます。 + +ルートディレクトリからリンクチェックやスタイルチェックを実行することもできます。 + +リンクチェックは出力フォルダを空にしてからビルドしてください。 + +``` +dactyl_link_checker +``` + +スタイルチェックは実験的なものです。 + +``` +dactyl_style_checker +``` + +## 設定ファイルのフォーマット + +このリポジトリでは、`dactyl-config.yml`ファイルのメタデータとページの[frontmatter](https://dactyl.link/frontmatter.html)を使って、ヘッダー、フッター、サイドバー、パンくずリストなどのナビゲーション要素を生成します。 + +新しいページを追加する場合、`dactyl-config.yml`ファイルのpages配列の適切な位置に追加する必要があります。追加例は次のようになります。 + +```yaml + - md: concepts/the-rippled-server/the-rippled-server.md + targets: + - en + - ja # 翻訳コンテンツがない場合、全てのターゲットを対象とします。 +``` + +Markdownファイル自体は、以下のようなfrontmatterで始まる必要があります。 + +```yaml +--- +html: the-rippled-server.html +parent: concepts.html +template: pagetype-category.html.jinja +blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server. +--- +``` + +少なくとも、ほとんどのページには `html`、`parent`、`blurb` フィールドが必要です(さらに、設定ファイルでは`md`フィールドと`targets`フィールドも必要です)。ここに、またはページの設定ファイルのエントリに任意のキーと値のペアを記述することができますが、以下のものが関係しています。 + +### 規約 + +ページを作成する際には、以下の規約に従ってください。 + +- HTMLのファイル名とMDのファイル名は、拡張子を除いて完全に一致していなければなりません。 +- ファイル名は"and"や"the"のような単語を含め、ページのタイトルと密接に一致する必要がありますが、スペースや句読点の代わりにハイフンを使用し、すべて小文字にする必要があります。例えば、`cash-a-check-for-an-exact-amount.md`のようにします。ページのタイトルを変更した場合は、ファイル名も変更する必要があります。(すでに別のURLで公開されている場合は、古いURLからのリダイレクトを残してください) +- 常にh1ヘッダーでページを始めます。 +- ページの一番上のh1アンカーにはリンクせず、アンカーなしでページ自体にリンクしてください。これは翻訳時のリンク切れを防ぐのに役立ちます。以降のヘッダーへのリンクは問題ありません。 +- ページのタイトルに書式( _italics_ や`code font`など)を使わないでください。 +- Markdownファイルのテキストを折り返さないでください。 +- コードサンプルの場合、行は80文字以下になるようにしてください。 +- 迷ったら、[Ciro SantilliのMarkdownスタイルガイド (Writability Profile)](https://cirosantilli.com/markdown-style-guide/)に従ってください。 +- ランディングページはサブフォルダに入れ、フォルダと同じファイル名とします。例えば、"Accounts"ページグループのランディングページは`accounts/accounts.md`で、HTMLファイル名は`accounts.html`です。 + + **注意:** `index.md`は利用しないでください。 + +- Markdownやコードサンプルでは、インデントにタブ文字を使用しないでください。**JavaScript**のコードサンプルでは、1字下げにつき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レジャーのネイティブデジタルアセットまたは暗号通貨。XRPはレジャーの外部の価値を表すトークンではありません。 | +| XRP Ledger | Ripple, リップル, Ripple Network, リップルネットワーク, RCL | XRP Ledgerは、過去に様々な場面で「リップルネットワーク」や「リップルコンセンサスレジャー」あるいは「RCL」と呼ばれていました。これらの名称は、コアサーバーのリファレンス実装を開発しているRipple(Ripple Labs)の社名と類似しているため、紛らわしく、廃止されました。 | +| XRPL | XRPL | _XRP Ledger_ の略です。_XRPL_ は不明瞭で、_XRP_ のタイプミスのように見えることがあります。 | + +## Frontmatterのフィールド + +このリポジトリのMarkdownファイルのfronmatterは任意のキーと値のペアを含むことができます。以下のフィールドは特定の用途や意味を持ちます。 + +| フィールド | 型 | 内容 | +|:---------------------|:-----------------|:-----------------------------------| +| `html` | String | ページの出力ファイル名。`.html`で終わり、ターゲット内で一意でなければなりません。翻訳版のページでは、ファイル名は英語版のページと同じにしてください。 | +| `parent` | String | ページの「親」ページの`html`の値。このページがナビゲーションのどこに表示されるかを示します。 | +| `blurb` | String | ページの要約文(プレーンテキストのみ)。ランディングページやソーシャルメディア上でリンクを展開する際のメタデータなど、さまざまな場所に表示されます。 | +| `name` | String | ページ名(プレーンテキストのみ)。 Markdownコンテンツのあるファイルでは、Dactylがコンテンツの最初の行のヘッダーから自動的に検出できるため、これを省略する必要があります。これは通常、Markdownファイルを持たないランディングページやその他の特別なページでのみ提供されます。 | +| `template` | String | このページで使用するテンプレートファイルのファイル名(`template/`ディレクトリ内)。ほとんどのページはデフォルトのテンプレートを使用します。`pagetype-category.html.jinja`テンプレートは最後に子ページのリストを表示します。特別な、あるいは特にユニークなレイアウトを持つページには、個別のテンプレートが必要になることがあります(通常、`page-`で始まります)。 | +| `status` | String | XRP Ledgerメインネットでまだ有効になっていない修正に関連するページでは、`not_enabled`を使用します。これにより、ナビゲーションのページの横にツールチップ付きの"フラスコ"バッジが表示されます。 | +| `nav_omit` | Boolean | ナビゲーション要素にこのページを表示しないようにするには`true`を使用します。 | +| `top_nav_omit` | Boolean | ページトップのドロップダウンナビゲーションに表示しないようにするには、`true`を使用します。 | +| `top_nav_level` | Number | トップナビのドロップダウンでページのインデントレベルを調整します。レベル`2`は、ドロップダウン内でその上のページの子のように表示されるようにインデントされます。 | +| `sidebar` | String | U左右のサイドバーを非表示にするには、`disabled`を使用します(ページがベーステンプレートから派生したテンプレートを使用している場合)。 | +| `fb_card` | String | Facebookでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 | +| `twitter_card` | String | Twitterでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 | +| `redirect_url` | String | `template: pagetype-redirect.html.jinja`でのみ使用します。ユーザがこのページに移動したときに、指定されたURLに自動的にリダイレクトします。 | +| `cta_text` | String | このページにリンクする「call to action」ボタンに表示されるテキスト(特別なランディングページにて表示されます)。 | +| `curated_anchors` | Array of Objects | 子ページと同様に、ランディングページに表示するためのアンカーです。配列の各オブジェクトは、人間が読める`name`フィールド(`"Available Modes"`など) と、リンク先のHTML IDを持つ`anchor`フィールド(`"#available-modes"`など)を持つ必要があります。 | +| `skip_spell_checker` | Boolean | `true`を使用すると、Dactylのスタイルチェッカーがこのページのスペルチェックをスキップします。 | +| `filters` | Array of Strings | このページで使用する追加フィルタのリストです。[フィルタ](https://github.com/ripple/dactyl/blob/master/README.md#filters)はPythonスクリプトで、ページ内容の事前または事後の追加処理を行います。 | +| `canonical_url` | String | クエリパラメータを受け取るページの正規URLを提供します。検索エンジンやその他のツールは、ページにリンクする際にこれを使用する可能性があります。 | +| `embed_xrpl_js` | Boolean | 最新版の[xrpl.js](https://js.xrpl.org)をこのページで読み込むには`true`を使用してください。 | diff --git a/content/resources/contribute-documentation/creating-diagrams.ja.md b/content/resources/contribute-documentation/creating-diagrams.ja.md new file mode 100644 index 00000000000..eaaf4782d9d --- /dev/null +++ b/content/resources/contribute-documentation/creating-diagrams.ja.md @@ -0,0 +1,33 @@ +--- +html: creating-diagrams.html +parent: contributing-to-documentation.html +blurb: ライトモードとダークモードの設定で適切に動作する図を作成します。 +--- +# 図の作成 + +このサイトには、SVGの図をライト・ダークモード用に自動的に再カラーリングするコードが含まれています。これは単に画像を反転させるだけではありません。再カラーリングは（ボトムライトに見えないように）グラデーションを同じ方向に保ち、色をその逆ではなくテーマに合った同等なものに置き換えます。例えば、"Ripple blue"は、その逆のオレンジではなく、XRPLグリーンに再カラーリングされます。 + +![色の反転とテーマ対応再カラーリングの比較](img/theme-aware-recolor.png) + +テーマを意識した再カラーリングでは、図のSVG形式の単一のソースファイルを使用し、CSSを使用して現在のテーマ（明暗）に合わせて再カラーリングされた図を生成します。ユーザがテーマを変更すると、図は即座にそれに合わせて変更されます。 + +テーマに対応した図をドキュメントに含めるには、以下のような構文で`include_svg`フィルタを使用します。 + +```jinja +{{ include_svg("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構造の中では使用することはできません。 + +> **注記:** フィルタのソースコードは[`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py)です。これは`lxml`がサイトを構築するための依存関係の一つである理由でもあります。 + +## 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)を参照してください)。 +- 可能な限り、埋め込みアイコン/画像の代わりにベクター図形を使用してください。画像の上にテキストを配置する必要がある場合は、テキスト要素に無地の背景を追加し、テーマがマッピングしている色のいずれかを使用してください。 +- テキストを含む透明な要素を、異なる背景色を持つ要素の上に重ねないでください。テキストを含む要素に直接背景色を適用してください。 diff --git a/content/resources/contribute-documentation/documentation-translations.ja.md b/content/resources/contribute-documentation/documentation-translations.ja.md new file mode 100644 index 00000000000..ed37ce45871 --- /dev/null +++ b/content/resources/contribute-documentation/documentation-translations.ja.md @@ -0,0 +1,74 @@ +--- +html: documentation-languages.html +parent: contributing-to-documentation.html +blurb: このウェブサイトにある文書の翻訳に貢献し、維持する方法を学びましょう。 +--- +# 翻訳 + +XRP Ledger Dev Portalは大部分が英語で書かれているため、一般的には英語版が最新かつ正確なバージョンです。しかしながら、XRP Ledgerのソフトウェアとコミュニティへのリーチを広げるために、このリポジトリには翻訳版のドキュメントも含まれています。私たちは、他の言語を理解するコミュニティのメンバーが、開発ポータルの内容を母国語で翻訳することを大いに歓迎します。 + +`dactyl-config.yml`には利用可能な言語ごとに"target"項目があります(2023-08-21現在、利用可能な言語は英語と日本語です)。このエントリには、次のようにテンプレートファイルで使用される文字列の定義が含まれます。 + +```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の各コンテンツページのエントリがあります。ページが翻訳されている場合、各翻訳ごとに個別の項目があり、その翻訳の“ターゲット"にリンクされています。ページがまだ翻訳されていない場合、すべてのターゲットで英語版が使用されます。 + +慣習上、ページのHTMLファイル名（`html`フィールド）はすべての言語バージョンで同じであるべきです。翻訳された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をあなたの母国語に翻訳したい場合は、まず[XRP Ledger Overview file](https://github.com/XRPLF/xrpl-dev-portal/blob/master/content/concepts/introduction/xrp-ledger-overview.md)から始めてください。 + +このファイルを`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エンコーディングを使用してください。バイトオーダーマークの使用は避けてください。 diff --git a/content/resources/contribute-documentation/documentation-translations.md b/content/resources/contribute-documentation/documentation-translations.md index 16228bd8c05..dcad609ab58 100644 --- a/content/resources/contribute-documentation/documentation-translations.md +++ b/content/resources/contribute-documentation/documentation-translations.md @@ -7,7 +7,7 @@ blurb: Learn how to contribute and maintain translations of the documentation on The XRP Ledger Dev Portal is mostly written in English, so the English version is generally the most up-to-date and accurate version. However, to broaden the reach of the XRP Ledger software and community, this repository also contains translated versions of the documentation. We strongly encourage members of the community who understand other languages to contribute translations of the dev portal contents in their native languages. -The `dactyl-config.yml` contains a "target" entry for each available language. (As of 2019-11-18, the available languages are English and Japanese.) This entry includes a dictionary of strings used in the template files. For example: +The `dactyl-config.yml` contains a "target" entry for each available language. (As of 2023-08-21, the available languages are English and Japanese.) This entry includes a dictionary of strings used in the template files. For example: ```yaml - name: en diff --git a/content/resources/contribute-documentation/tutorial-guidelines.ja.md b/content/resources/contribute-documentation/tutorial-guidelines.ja.md new file mode 100644 index 00000000000..e544bec111f --- /dev/null +++ b/content/resources/contribute-documentation/tutorial-guidelines.ja.md @@ -0,0 +1,83 @@ +--- +html: tutorial-guidelines.html +parent: contribute.html +blurb: このサイトのチュートリアルの構成と、質の高いチュートリアルを投稿するためのガイドラインを学びましょう。 +--- +# チュートリアルガイドライン + +私たちは、開発者が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ファイルを使用してください。 + +可能な限り、他のモジュールのコードを再利用してください。以前のモジュールの動作を変更する必要がある場合があります。関数名をオーバーロードするか、モジュールを修正して別の名前で保存してください。 diff --git a/content/resources/contribute-documentation/tutorial-guidelines.md b/content/resources/contribute-documentation/tutorial-guidelines.md index caa318d07dc..71527eda783 100644 --- a/content/resources/contribute-documentation/tutorial-guidelines.md +++ b/content/resources/contribute-documentation/tutorial-guidelines.md @@ -31,7 +31,7 @@ Add into that Ralph Smedley’s quote, “We learn best in moments of enjoyment. # Sample Code vs. Tasks vs. Concepts vs. Tutorials -To date, there have been some blurred lines where different types of documentation show up as _Tutorials._ Here are some comparisons that help define the distinction. +To date, there have been some blurred lines where different types of documentation show up as _Tutorials_. Here are some comparisons that help define the distinction. ## Sample Code @@ -81,5 +81,3 @@ For example, the first NFT tutorial shows how to mint, retrieve, and burn an NFT Don’t focus too much on the UX of the application, unless the look and feel is pertinent to the topic. Use the standard CSS file with the look and feel for all of the tutorials. Reuse the code from other modules when possible. There might be situations where you need to modify the behavior from an earlier module. You can either overload the function name or modify the module and save it with a different name. - - diff --git a/content/resources/contribute-documentation/tutorial-structure.ja.md b/content/resources/contribute-documentation/tutorial-structure.ja.md new file mode 100644 index 00000000000..3d6a86ba3c8 --- /dev/null +++ b/content/resources/contribute-documentation/tutorial-structure.ja.md @@ -0,0 +1,54 @@ +--- +html: tutorial-structure.html +parent: contribute.html +blurb: 一般的なチュートリアルの構成要素の要約です。 +--- +# チュートリアルの構成 + +各XRP Ledgerチュートリアルは、同一のフォーマットで構成されています。 + +1. チュートリアルで説明する機能の簡単な説明。 +2. コードを実行するための前提条件(必要な場合)、またはサンプルコードへのリンク。 +3. チュートリアルの機能の使用例。 +4. サンプルコードの解説と、そのスクリプトの特徴的な要素の紹介。 +5. 次のステップとして試すべき概念的な情報や優れたチュートリアルへのリンク。 + +セットアップ(前提条件)と使用方法とコード開発は分けて考えましょう。これらはそれぞれ異なる活動であり、それぞれ脳の異なる領域を動かします。この3つの要素を一度に考えようとすると、混乱につながります。 + +## 説明 + +![説明](img/tut-struct1.png) + +そのサンプルが何を示しているかを記載してください。可能であれば、各サンプルには関連する特定のタスクを達成するための手順を記述してください。(NFTの売却オファーの作成、売却オファーの受け入れ、売却オファーの削除など)。チュートリアルで説明されている内容を理解するのに十分なコンセプトに関する情報を記載し、必要であれば、追加情報へのリンクも記載します。 + +## 前提条件 + +![前提条件](img/tut-struct2.png) + +必要なソフトウェアと、チュートリアルを実行するために必要なすべてのサンプルコードへのリンクを提供します。必要であれば、サードパーティのツールの使い方を簡単に説明しますが、ユーザが自由に深く掘り下げることができるように、ソースとなるウェブサイトへのリンクを提供します。 + +## 使用例 + +![使用例](img/tut-struct3.png) + +チュートリアルのアプリケーションの完成した動作例を提供することから始めましょう。これは、ソフトウェアを使って問題を解決するチャンスです。 +　 +チュートリアルの各ステップにはスクリーンショットを使用してください。これによって、ユーザは自分でコードを実行しなくてもチュートリアルを理解することができます。もちろん、コードを実行することが _望ましい_ ですが、これにりユーザに選択肢を与えることができます。 + +適切な条件におけるシナリオを記述してください。インターネットへの接続が途切れなければ、アプリケーションは問題なく動作するはずです。チュートリアルに関連しないトラブルシューティングの情報を提供しないでください。 + +## コード解説 + +![コード解説](img/tut-struct4.png) + +コードを1ブロックずつ見ていきましょう。既に説明したトピックを繰り返さないでください。サンプルコードには、HTML構文のような基本的な部分のプログラミング方法については、その実装に独自なものがない限り、詳細な説明はしないでください。 + +強調すべき重要なことは、XRPLとのやりとりはすべてトランザクションかリクエストであり、すべてのトランザクションとリクエストは本質的に同じであるということです。私たちが提供するサンプルコードは、トランザクションやリクエストを準備する方法と、返された結果を処理する方法を示しています。1つのトランザクションやリクエストをどのように送信しどのようなレスポンスを返すかを知ることは、他のトランザクションやリクエストの処理について非常に良いヒントとなります。 + +(技術的には、リクエストに似た第3のカテゴリーがあります。[Subscriptionメソッド](subscription-methods.html)をご覧ください)。 + +## 関連項目 + +![関連項目](img/tut-struct5.png) + +チュートリアルの最後には、追加の資料、概念的な情報、学習のにおいて有益な次のステップとなるチュートリアルへのリンクを提供します。 diff --git a/dactyl-config.yml b/dactyl-config.yml index 3f0edeaa213..3cb08bbcfde 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -5039,27 +5039,34 @@ pages: # Contribute Code --------------------------------------------------------- - # TODO: translate - md: resources/contribute-code/contribute-code.md top_nav_grouping: Join In targets: - en + + - md: resources/contribute-code/contribute-code.ja.md + top_nav_grouping: 参加する + targets: - ja - # TODO: translate - md: resources/contribute-code/create-custom-transactors.md targets: - en + + - md: resources/contribute-code/create-custom-transactors.ja.md + targets: - ja # Contribute Documentation ------------------------------------------------ - # TODO: Translate section. - - md: resources/contribute-documentation/contribute-documentation.md top_nav_grouping: Join In targets: - en + + - md: resources/contribute-documentation/contribute-documentation.ja.md + top_nav_grouping: 参加する + targets: - ja - name: Contributor Code of Conduct @@ -5077,21 +5084,33 @@ pages: - md: resources/contribute-documentation/documentation-translations.md targets: - en + + - md: resources/contribute-documentation/documentation-translations.ja.md + targets: - ja - md: resources/contribute-documentation/creating-diagrams.md targets: - en + + - md: resources/contribute-documentation/creating-diagrams.ja.md + targets: - ja - md: resources/contribute-documentation/tutorial-guidelines.md targets: - en + + - md: resources/contribute-documentation/tutorial-guidelines.ja.md + targets: - ja - md: resources/contribute-documentation/tutorial-structure.md targets: - en + + - md: resources/contribute-documentation/tutorial-structure.ja.md + targets: - ja @@ -5108,13 +5127,14 @@ pages: targets: - en - # TODO: translate blurb & contents - - name: 貢献する + # TODO: translate contents + - name: XRPLコミュニティへの貢献 html: contribute.html parent: index.html template: page-community.html.jinja sidebar: disabled - blurb: 話題に加わろう + top_nav_blurb: Join the conversation + blurb: XRP Ledger (XRPL) はコミュニティ主導のパブリックブロックチェーンです。ここでは、その参加方法について説明します。 top_nav_name: コミュニティ top_nav_hero_image: top-nav-hero-contribute targets: @@ -5254,10 +5274,12 @@ pages: targets: - ja - # TODO: Translate - md: contributing/report-a-scam.md targets: - en + + - md: contributing/report-a-scam.ja.md + targets: - ja # Redirects from deprecated "Explore" pages ------------------------------------