Ansible devel - en to ja translation catalogue (3080 entries)

en: Collection Galaxy metadata structure
ja: コレクション Galaxy メタデータ構造

en: A key component of an Ansible collection is the ``galaxy.yml`` file placed in the root directory of a collection. This file contains the metadata of the collection that is used to generate a collection artifact.
ja: Ansible コレクションの主なコンポーネントは、コレクションのルートディレクトリーに置いてある ``galaxy.yml`` ファイルです。このファイルには、コレクションアーティファクトの生成に使用されるコレクションのメタデータが含まれます。

en: Structure
ja: 構造

en: The ``galaxy.yml`` file must contain the following keys in valid YAML:
ja: ``galaxy.yml`` ファイルの有効な YAML に以下のキーが含まれている必要があります。

en: Key
ja: キー

en: Comment
ja: コメント

en: string |_|
ja: 文字列 |_|

en: required
ja: 必須

en: The namespace of the collection.
ja: コレクションの名前空間。

en: This can be a company/brand/organization or product namespace under which all content lives.
ja: これには、企業/ブランド/組織、またはすべてのコンテンツが置かれる製品の名前空間を指定できます。

en: May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with underscores or numbers and cannot contain consecutive underscores.
ja: 英数字 (小文字) とアンダースコアのみを使用できます。名前空間はアンダースコアや数字で開始できず、連続したアンダースコアを含めることはできません。

en: The name of the collection.
ja: コレクションの名前。

en: Has the same character restrictions as ``namespace``.
ja: ``namespace`` と同じ文字制限があります。

en: The version of the collection.
ja: コレクションのバージョン。

en: Must be compatible with semantic versioning.
ja: セマンティックバージョニングと互換性がある必要があります。

en: The path to the Markdown (.md) readme file.
ja: マークダウン (.md) readme ファイルへのパス。

en: This path is relative to the root of the collection.
ja: このパスは、コレクションのルートに相対します。

en: list |_|
ja: リスト |_|

en: A list of the collection's content authors.
ja: コレクションのコンテンツ作成者の一覧。

en: Can be just the name or in the format 'Full Name <email> (url) @nicks:irc/im.site#channel'.
ja: 名前または形式には、「氏名 <email> (url) @nicks:irc/im.site#channel」の形式しか指定できません。

en: A short summary description of the collection.
ja: コレクションの簡単な説明。

en: Either a single license or a list of licenses for content inside of a collection.
ja: コレクション内の 1 つのライセンスまたはコンテンツのライセンスの一覧。

en: Ansible Galaxy currently only accepts `SPDX <https://spdx.org/licenses/>`_ licenses
ja: 現在 Ansible Galaxy は `SPDX <https://spdx.org/licenses/>`_ ライセンスのみ受け付けます。

en: This key is mutually exclusive with ``license_file``.
ja: このキーは、``license_file`` と相互に排他的です。

en: The path to the license file for the collection.
ja: コレクションのライセンスファイルへのパス。

en: This key is mutually exclusive with ``license``.
ja: このキーは、``license`` と相互に排他的です。

en: A list of tags you want to associate with the collection for indexing/searching.
ja: インデックス化/検索のコレクションに関連付けるタグの一覧。

en: A tag name has the same character requirements as ``namespace`` and ``name``.
ja: タグ名には、``namespace`` および ``name`` と同じ文字要件があります。

en: dictionary |_|
ja: ディクショナリー |_|

en: Collections that this collection requires to be installed for it to be usable.
ja: 利用できるように、このコレクションをインストールする必要があるコレクション。

en: The key of the dict is the collection label ``namespace.name``.
ja: ディクショナリーのキーはコレクションラベル ``namespace.name`` です。

en: The value is a version range `specifiers <https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification>`_.
ja: この値は、`指定子 <https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification>`_ のバージョン範囲です。

en: Multiple version range specifiers can be set and are separated by ``,``.
ja: 複数のバージョン範囲指定子を設定でき、``,`` で区切ることができます。

en: The URL of the originating SCM repository.
ja: 元の SCM リポジトリーの URL。

en: The URL to any online docs.
ja: オンラインドキュメントへの URL。

en: The URL to the homepage of the collection/project.
ja: コレクション/プロジェクトのホームページへの URL。

en: The URL to the collection issue tracker.
ja: コレクションの問題トラッカーへの URL。

en: A list of file glob-like patterns used to filter any files or directories that should not be included in the build artifact.
ja: ビルドアーティファクトに含まれないファイルやディレクトリーをフィルタリングするのに使用されるファイルグロブのようなパターンの一覧。

en: A pattern is matched from the relative path of the file or directory of the collection directory.
ja: パターンは、コレクションディレクトリーのファイルまたはディレクトリーの相対パスから照合されます。

en: This uses ``fnmatch`` to match the files or directories.
ja: ここでは、``fnmatch`` を使用してファイルまたはディレクトリーを照合します。

en: Some directories and files like ``galaxy.yml``, ``*.pyc``, ``*.retry``, and ``.git`` are always filtered.
ja: ``galaxy.yml``、``*.pyc``、``*.retry``、``.git`` などの一部のディレクトリーおよびファイルは常にフィルタリングされます。

en: Examples
ja: 例

en: Develop or modify a collection.
ja: コレクションを開発するか、または変更します。

en: Learn about how to write Ansible modules
ja: Ansible モジュールの作成方法について

en: Learn how to install and use collections.
ja: コレクションのインストール方法および使用方法はこちらを参照してください。

en: The development mailing list
ja: 開発メーリングリスト

en: #ansible IRC chat channel
ja: IRC チャットチャンネル (#ansible)

en: Debugging modules
ja: モジュールのデバッグ

en: Detailed debugging steps
ja: 詳細なデバッグ手順

en: Ansible modules are put together as a zip file consisting of the module file and the various Python module boilerplate inside of a wrapper script. To see what is actually happening in the module, you need to extract the file from the wrapper. The wrapper script provides helper methods that let you do that.
ja: Ansible モジュールは、モジュールファイルとラッパースクリプト内のさまざまな Python モジュールの boilerplate で構成される zip ファイルとしてまとめて置かれます。モジュールで実際に何が発生しているかを確認するには、ラッパーからファイルを抽出する必要があります。ラッパースクリプトは、これを可能にするヘルパーメソッドを提供します。

en: The following steps use ``localhost`` as the target host, but you can use the same steps to debug against remote hosts as well. For a simpler approach to debugging without using the temporary files, see :ref:`simple debugging <simple_debugging>`.
ja: 以下の手順では、ターゲットホストに ``localhost`` を使用していますが、同じ手順を使用してリモートホストに対してデバッグすることもできます。一時ファイルを使用せずにデバッグを行う簡単な方法は、「:ref:`簡単なデバッグ <simple_debugging>`」を参照してください。

en: Set :envvar:`ANSIBLE_KEEP_REMOTE_FILES` to ``1`` on the control host so Ansible will keep the remote module files instead of deleting them after the module finishes executing. Use the ``-vvv`` option to make Ansible more verbose. This will display the file name of the temporary module file.
ja: コントロールホストで :envvar:`ANSIBLE_KEEP_REMOTE_FILES` を ``1`` に設定します。これにより、Ansible はモジュール実行後も削除せずにリモートモジュールファイルを維持します。``-vvv`` オプションを使用すると、Ansible の詳細が表示されます。一時モジュールファイルのファイル名が表示されます。

en: Navigate to the temporary directory from the previous step. If the previous command was run against a remote host, connect to that host first before trying to navigate to the temporary directory.
ja: 前の手順から一時ディレクトリーに移動します。前のコマンドがリモートホストに対して実行した場合は、最初にそのホストに接続します。一時ディレクトリーに移動する前に、そのホストに接続します。

en: Run the wrapper's ``explode`` command to turn the string into some Python files that you can work with.
ja: ラッパーの ``explode`` コマンドを実行して、文字列を使用可能な Python ファイルに変換します。

en: If you want to examine the wrapper file you can. It will show a small Python script with a large base64 encoded string. The string contains the module to execute.
ja: ラッパーファイルを調べたい場合は、小さい Python スクリプトに、大きな base64 でエンコードされた文字列が記載されます。文字列には、実行するモジュールが含まれます。

en: When you look into the temporary directory you'll see a structure like this:
ja: 一時ディレクトリーを確認すると、以下のような構造が表示されます。

en: ``AnsiballZ_ping.py`` is the Python script with the module code stored in a base64 encoded string. It contains various helper functions for executing the module.
ja: ``AnsiballZ_ping.py`` base64 でエンコードされた文字列に保存されたモジュールコードを含む Python スクリプトで、モジュールを実行するためのさまざまなヘルパー関数が含まれます。

en: ``ping.py`` is the code for the module itself. You can modify this code to see what effect it would have on your module, or for debugging purposes.
ja: ``ping.py`` は、モジュール自体のコードです。このコードを変更して、モジュールまたはデバッグの目的を確認することができます。

en: The ``args`` file contains a JSON string. The string is a dictionary containing the module arguments and other variables that Ansible passes into the module to change its behavior. Modify this file to change the parameters passed to the module.
ja: ``args`` ファイルには JSON 文字列が含まれています。この文字列は、モジュール引数および、Ansible がモジュールに渡すその他の変数を含むディクショナリーで、動作を変更します。このファイルを変更して、モジュールに渡されるパラメーターを変更します。

en: The ``ansible`` directory contains the module code in ``modules`` as well as code from :mod:`ansible.module_utils` that is used by the module. Ansible includes files for any :mod:`ansible.module_utils` imports in the module but not any files from any other module. If your module uses :mod:`ansible.module_utils.url` Ansible will include it for you. But if your module includes `requests <https://requests.readthedocs.io/en/master/api/>`_, then you'll have to make sure that the Python `requests library <https://pypi.org/project/requests/>`_ is installed on the system before running the module.
ja: ``ansible`` ディレクトリーには、``modules`` のモジュールコードと、モジュールに使用される :mod:`ansible.module_utils` のコードが含まれています。Ansible には、モジュール内の :mod:`ansible.module_utils` インポートのファイルが含まれますが、他のモジュールからのファイルは含まれません。モジュールで :mod:`ansible.module_utils.url` が使用される場合は、Ansible にそれが含まれます。ただし、モジュールに `requests <https://requests.readthedocs.io/en/master/api/>`_ が含まれる場合は、モジュールを実行する前に Python `requests ライブラリー <https://pypi.org/project/requests/>`_ がシステムにインストールされていることを確認する必要があります。

en: You can modify files in this directory if you suspect that the module is having a problem in some of this boilerplate code rather than in the module code you have written.
ja: 作成したモジュールコードではなく、モジュールのこの boilerplate コードの一部に問題があると思われる場合は、このディレクトリーのファイルを変更できます。

en: Once you edit the code or arguments in the exploded tree, use the ``execute`` subcommand to run it:
ja: 展開されたツリーのコードまたは引数を編集したら、``execute`` サブコマンドを使用してこれを実行します。

en: This subcommand inserts the absolute path to ``debug_dir`` as the first item in ``sys.path`` and invokes the script using the arguments in the ``args`` file. You can continue to run the module like this until you understand the problem. Then you can copy the changes back into your real module file and test that the real module works via ``ansible`` or ``ansible-playbook``.
ja: このサブコマンドは、``sys.path`` の最初の項目として ``debug_dir`` に絶対パスを挿入し、``args`` ファイルの引数を使用してスクリプトを呼び出します。問題を理解するまで、このモジュールの実行を継続できます。変更を実際のモジュールファイルにコピーし、実際のモジュールが ``ansible`` または ``ansible-playbook`` で動作することをテストすることができます。

en: Simple debugging
ja: 簡単なデバッグ

en: The easiest way to run a debugger in a module, either local or remote, is to use `epdb <https://pypi.org/project/epdb/>`_. Add ``import epdb; epdb.serve()`` in the module code on the control node at the desired break point. To connect to the debugger, run ``epdb.connect()``. See the `epdb documentation <https://pypi.org/project/epdb/>`_ for how to specify the ``host`` and ``port``. If connecting to a remote node, make sure to use a port that is allowed by any firewall between the control node and the remote node.
ja: モジュール (ローカルまたはリモートのいずれか) でデバッガーを実行する最も簡単な方法は、`epdb <https://pypi.org/project/epdb/>`_ を使用します。任意のブレークポイントで、コントロールノードのモジュールコードに ``import epdb; epdb.serve()`` を追加します。デバッガーに接続するには、``epdb.connect()`` を実行します。``host`` および ``port`` を指定する方法は、`epdb ドキュメント <https://pypi.org/project/epdb/>`_ を参照してください。リモートノードに接続する場合は、コントロールノードとリモートノードとの間のファイアウォールが許可されているポートを使用するようにしてください。

en: This technique should work with any remote debugger, but we do not guarantee any particular remote debugging tool will work.
ja: この手法はリモートデバッガーと動作しますが、特定のリモートデバッグツールが機能する保証はありません。

en: The `q <https://pypi.org/project/q/>`_ library is another very useful debugging tool.
ja: `q <https://pypi.org/project/q/>`_ ライブラリーは、もう 1 つの便利なデバッグツールです。

en: Since ``print()`` statements do not work inside modules, raising an exception is a good approach if you just want to see some specific data. Put ``raise Exception(some_value)`` somewhere in the module and run it normally. Ansible will handle this exception, pass the message back to the control node, and display it.
ja: ``print()`` ステートメントはモジュール内では機能しないため、特定のデータを確認する場合は例外を発生させます。モジュール内のどこかに ``raise Exception(some_value)`` を置き、通常どおり実行します。Ansible はこの例外を処理し、メッセージをコントロールノードに渡し、表示します。

en: Topics
ja: トピック

en: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ first.
ja: この API は、内部 Ansible の使用を目的としています。Ansible は、古いバージョンの API との後方互換性を妨げる可能性がある時点でこの API に変更を加えることができるため、Ansible では外部の使用はサポートされません。Playbook またはモジュールの実行のみに Python API を使用する場合は、まず `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ を考慮してください。

en: There are several ways to use Ansible from an API perspective.   You can use the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can write plugins, and you can plug in inventory data from external data sources.  This document gives a basic overview and examples of the Ansible execution and playbook API.
ja: API パースペクティブから Ansible を使用する方法は複数あります。Ansible Python API を使用してノードを制御し、Ansible を拡張してさまざまな Python イベントに応答でき、プラグインを作成したり、外部データソースからのインベントリーデータへのプラグインを行うことができます。本書では、Ansible の実行および Playbook API の基本的な概要と例を紹介します。

en: If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously, or have access control and logging demands, please see the `AWX project <https://github.com/ansible/awx/>`_.
ja: Python 以外の言語で Ansible を使用して、イベントを非同期的にトリガーするか、アクセス制御およびログ要求をする場合は、「`AWX プロジェクト <https://github.com/ansible/awx/>`_」を参照してください。

en: Because Ansible relies on forking processes, this API is not thread safe.
ja: Ansible はプロセスのフォークに依存しているため、この API はスレッドセーフではありません。

en: Python API example
ja: Python API の例

en: This example is a simple demonstration that shows how to minimally run a couple of tasks:
ja: この例は、いくつかのタスクを最小限に実行する方法を示す簡単なデモです。

en: Ansible emits warnings and errors via the display object, which prints directly to stdout, stderr and the Ansible log.
ja: Ansible は、表示オブジェクトを介して警告とエラーを出力します。標準出力 (stdout)、標準エラー (stderr)、Ansible ログに直接出力します。

en: The source code for the ``ansible`` command line tools (``lib/ansible/cli/``) is `available on GitHub <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli>`_.
ja: ``ansible`` コマンドラインツールのソースコード (``lib/ansible/cli/``) は `GitHub で利用 <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli>`_ できます。

en: Developing dynamic inventory integrations
ja: 動的インベントリー統合の開発

en: Getting started on developing a module
ja: モジュール開発を始める

en: How to develop plugins
ja: プラグインの開発方法

en: Mailing list for development topics
ja: 開発トピックのメーリングリスト

en: Developing new collections
ja: 新規コレクションの開発

en: Working with existing collections
ja: 既存コレクションの使用

en: Collections references
ja: コレクションの参照

en: Developing collections
ja: コレクションの開発

en: Collections are a distribution format for Ansible content. You can package and distribute playbooks, roles, modules, and plugins using collections. A typical collection addresses a set of related use cases. For example, the ``cisco.ios`` collection automates management of Cisco IOS devices.
ja: コレクションは、Ansible コンテンツのディストリビューション形式です。コレクションを使用して Playbook、ロール、モジュール、およびプラグインをパッケージ化および分散できます。一般的なコレクションでは、関連する一連のユースケースに対応します。たとえば、``cisco.ios`` コレクションは Cisco IOS デバイスの管理を自動化します。

en: You can create a collection and publish it to `Ansible Galaxy <https://galaxy.ansible.com>`_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform.
ja: コレクションを作成して、`Ansible Galaxy <https://galaxy.ansible.com>`_ またはプライベート Automation Hub インスタンスに公開できます。Red Hat Ansible Automation Platform の一部である認定コレクションを Red Hat Automation Hub に公開できます。

en: For instructions on developing modules, see :ref:`developing_modules_general`.
ja: モジュール開発の手順は、「:ref:`developing_modules_general`」を参照してください。

en: Learn how to install and use collections in playbooks and roles
ja: Playbook およびロールでコレクションをインストールして使用する方法を説明します。

en: Guidelines for contributing to selected collections
ja: 選択したコレクションに貢献するガイドライン

en: Current development status of community collections and FAQ
ja: コミュニティーコレクションおよび FAQ の現在の開発ステータス

en: Generating changelogs and porting guide entries in a collection
ja: コレクションで変更ログおよび移植ガイドエントリーの生成

en: You can create and share changelog and porting guide entries for your collection. If your collection is part of the Ansible Community package, we recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
ja: コレクションの変更ログおよび移植ガイドを作成して共有できます。コレクションが Ansible Community パッケージの一部である場合は、`antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ ツールを使用して Ansible 互換の変更ログを生成することが推奨されます。Ansible の変更ログでは、このツールを使用して、このツールの出力を使用して、Ansible リリースに含まれるすべてのコレクションを、このリリースに対して 1 つの変更ログにまとめることが推奨されます。

en: Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
ja: Ansible は、指定したコレクションセットを含む Ansible 2.10 以降のリリースを参照します。

en: Understanding antsibull-changelog
ja: antsibull-changelog について

en: The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
ja: ``antsibull-changelog`` ツールを使用すると、組み合わせた Ansible の変更ログと互換性のある Ansible コレクションに対して変更ログを作成し、更新できます。これは、Ansible リリース以前で使用される変更ログジェネレーターに対する更新です。このツールは、``breaking_changes``、``security_fixes``、および ``trivial`` の 3 つの新しい変更ログフラグメントカテゴリーを追加します。このツールは、Ansible がリリースを組み合わせた ``CHANGELOG.rst`` ファイルと移植ガイドを作成するために使用する ``changelog.yaml`` ファイルも生成します。

en: See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
ja: 詳細は、「:ref:`changelogs_how_to`」および `antsibull-changelog ドキュメント <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ を参照してください。

en: The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
ja: コレクションのメンテナーは、コレクションに変更ログポリシーを設定します。詳細は、個々のコレクションの貢献ガイドラインを参照してください。

en: Generating changelogs
ja: 変更ログの生成

en: To initialize changelog generation:
ja: 変更ログの生成を初期化するには、以下を実行します。

en: Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`.
ja: ``antsibull-changelog`` をインストールします (:code:`pip install antsibull-changelog`)。

en: Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
ja: リポジトリーの変更ログを初期化します (:code:`antsibull-changelog init <path/to/your/collection>`)。

en: Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
ja: 必要に応じて、``changelogs/config.yaml`` ファイルを編集して、生成された変更ログの ``.rst`` ファイルまたはその他のオプションをカスタマイズします。詳細は、「`コレクションの変更ログのブートストラップ <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_」を参照してください。

en: To generate changelogs from the changelog fragments you created:
ja: 作成した変更ログフラグメントから変更ログを生成するには、以下を実行します。

en: Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
ja: 必要に応じて、変更ログフラグメントを検証します (:code:`antsibull-changelog lint`) 。

en: Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
ja: リリースの変更ログ (:code:`antsibull-changelog release [--version version_number]`) を生成します。

en: Add the  ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
ja: 以前に ``antsibull-changelog release`` コマンドを実行し、コレクションのバージョンが変更されていない場合は、``--reload-plugins`` オプションを追加します。``antsibull-changelog`` はすべてのプラグインに関する情報をキャッシュし、コレクションバージョンが変更されるまでキャッシュを更新しません。

en: Porting Guide entries from changelog fragments
ja: 変更ログフラグメントの移植ガイドのエントリー

en: The Ansible changelog generator automatically adds several changelog fragment categories to the Ansible Porting Guide:
ja: Ansible 変更ログジェネレーターは、複数の変更ログフラグメントカテゴリーを Ansible 移植ガイドに自動的に追加します。

en: Including collection changelogs into Ansible
ja: Ansible へのコレクション変更ログの追加

en: If your collection is part of Ansible, use one of the following three options  to include your changelog into the Ansible release changelog:
ja: コレクションが Ansible の一部である場合は、以下の 3 つのオプションのいずれかを使用して、作成した変更ログを、Ansible リリースの 変更ログに追加します。

en: Use the ``antsibull-changelog`` tool.
ja: ``antsibull-changelog`` ツールの使用

en: If are not using this tool, include the properly formatted ``changelog.yaml`` file  into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
ja: このツールを使用していない場合は、適切に形式化された ``changelog.yaml`` ファイルをコレクションに追加します。詳細は、「`changelog.yaml 形式 <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_」を参照してください。

en: Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
ja: この情報への HTML リンクで問題を https://github.com/ansible-community/ansible-build-data/ で開いて、任意の形式で独自の変更ログまたはリリースノートへのリンクを追加します。

en: For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
ja: 最初の 2 つのオプションの場合、Ansible は変更ログの詳細を Galaxy からプルし、変更ログを今後の Ansible リリースに含まれる Galaxy のコレクションバージョンに追加する必要があります。

en: Contributing to collections
ja: コレクションへの貢献

en: If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``). You should first check the collection repository to see if it has specific contribution guidelines. These are typically listed in the README.md or CONTRIBUTING.md files within the repository.
ja: 既存のコレクションに機能を追加するには、バグを修正するために使用するコレクションを変更したり、コレクションのモジュールの動作を変更して、そのコレクションの git リポジトリーのクローンを作成し、ブランチに変更を加えます。コレクションへの変更を、Ansible (``source hacking/env-setup``)の ローカルチェックアウトと組み合わせることができます。まず、コレクションリポジトリーを確認して、特定の貢献ガイドラインが含まれているかどうかを確認します。通常、それらはリポジトリーの README.md ファイルまたは CONTRIBUTING.md ファイルに一覧表示されます。

en: Contributing to a collection: community.general
ja: コレクションへの貢献: community.general

en: These instructions apply to collections hosted in the `ansible_collections GitHub org <https://github.com/ansible-collections>`_. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
ja: これらの手順は、`ansible_collections GitHub org <https://github.com/ansible-collections>`_ にホストされるコレクションに適用されます。特に GitHub でホストされていないコレクションについては、これに貢献する情報について、コレクションの ``README.md`` を確認してください。

en: This example uses the `community.general collection <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections in the same GitHub org, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection.
ja: この例では、`community.general コレクション <https://github.com/ansible-collections/community.general/>`_ を使用しています。同じ GitHub Org の他のコレクションに貢献するために、フォルダー名 ``community`` および ``general`` を、別のコレクションの名前空間およびコレクション名に置き換えます。

en: Prerequisites
ja: 要件

en: Include ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`
ja: :ref:`COLLECTIONS_PATHS` に ``~/dev/ansible/collections/`` を含めます

en: If that path mentions multiple directories, make sure that no other directory earlier in the search path contains a copy of ``community.general``.
ja: そのパスで複数のディレクトリーに言及されている場合は、検索パスの前のその他のディレクトリーに ``community.general`` のコピーが含まれないようにします。

en: Creating a PR
ja: PR の作成

en: Create the directory ``~/dev/ansible/collections/ansible_collections/community``::
ja: ``~/dev/ansible/collections/ansible_collections/community`` ディレクトリーを作成します。

en: Clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the directory ``general``::
ja: `community.general Git リポジトリー <https://github.com/ansible-collections/community.general/>`_ のクローンを作成するか、それを ``general`` ディレクトリーにフォークします。

en: If you clone from a fork, add the original repository as a remote ``upstream``::
ja: フォークのクローンを作成したら、元のリポジトリーをリモートの ``upstream`` として追加します。

en: Create a branch and commit your changes on the branch.
ja: ブランチを作成し、ブランチで変更をコミットします。

en: Remember to add tests for your changes, see :ref:`testing_collections`.
ja: 変更にテストを追加するのを忘れないようにしてください。:ref:`testing_collections` を参照してください。

en: Push your changes to your fork of the collection and create a Pull Request.
ja: 変更をコレクションのフォークにプッシュし、プル要求を作成します。

en: You can test your changes by using this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch.
ja: これで、``ansible/ansible`` の ``devel`` ブランチのローカルチェックアウトを含め、ローカルにインストールしたどのバージョンの Ansible でも、Playbook やロールで ``community.general`` のチェックアウトを使用して変更をテストできます。

en: Creating collections
ja: コレクションの作成

en: To create a collection:
ja: コレクションを作成するには、以下を行います。

en: Create a :ref:`collection skeleton<creating_collections_skeleton>` with the ``collection init`` command.
ja: ``collection init`` コマンドで :ref:`collection skeleton<creating_collections_skeleton>` を作成します。

en: Add modules and other content to the collection.
ja: モジュールおよびその他のコンテンツをコレクションに追加します。

en: Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<building_collections>`.
ja: :ref:`ansible-galaxy collection build<building_collections>` を使用してコレクションをコレクションアーティファクトにビルドします。

en: Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publishing_collections>`.
ja: :ref:`ansible-galaxy collection publish<publishing_collections>` で構築したコレクションアーティファクトを Galaxy に公開します。

en: A user can then install your collection on their systems.
ja: これにより、ユーザーが、そのコレクションをシステムにインストールできるようになります。

en: Creating a collection skeleton
ja: コレクションスケルトンの作成

en: To start a new collection:
ja: 新規コレクションを開始するには、以下を使用します。

en: Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
ja: 名前空間とコレクション名はいずれも、同じ厳密な要件セットを使用します。これらの要件については、Galaxy ドキュメントスイートの「`Galaxy 名前空間 <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_」で確認してください。

en: Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
ja: スケルトンが存在すると、コレクション内の内容でディレクトリーを設定できます。`ansible-collections <https://github.com/ansible-collections/>`_ の GitHub Org で、コレクションに配置できる内容を十分に理解することができます。

en: Reference: the ``ansible-galaxy collection`` command
ja: 参照: ``ansible-galaxy collection`` コマンド

en: Currently the ``ansible-galaxy collection`` command implements the following sub commands:
ja: 現在、``ansible-galaxy collection`` コマンドは以下のサブコマンドを実装します。

en: ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template.
ja: ``init``: Ansible に含まれるデフォルトテンプレートまたは独自のテンプレートに基づいて、基本的なコレクションのスケルトンを作成します。

en: ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
ja: ``build``: Galaxy または独自のリポジトリーにアップロードできるコレクションアーティファクトを作成します。

en: ``publish``: Publish a built collection artifact to Galaxy.
ja: ``publish``: 構築したコレクションアーティファクトを Galaxy に公開します。

en: ``install``: Install one or more collections.
ja: ``install``: 1 つ以上のコレクションをインストールします。

en: To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
ja: ``ansible-galaxy`` コマンドラインツールの詳細は、:ref:`ansible-galaxy` の man ページを参照してください。

en: Directories and files included in the collection skeleton
ja: コレクションスケルトンに含まれるディレクトリーおよびファイル

en: Distributing collections
ja: コレクションの配布

en: You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
ja: コレクションは、ディストリビューションサーバーに公開することで配布できます。ディストリビューションサーバーには、Ansible Galaxy、Red Hat Automation Hub、およびプライベートにホストされている Automation Hub インスタンスが含まれます。すべてのコレクションを Ansible Galaxy や、プライベートにホストされた Automation Hub インスタンスに公開できます。コレクションが Red Hat によって認定されている場合は、Red Hat Automation Hub に公開できます。

en: Distributing collections involves three major steps: #. Configuring your distribution server(s) #. Building your collection artifact #. Publishing your collection
ja: コレクションの配布には、#. ディストリビューションサーバーの設定 #. コレクションアーティファクトのビルド #. コレクションの公開の 3 つの大きなステップが関係します。

en: Configuring your distribution server or servers
ja: ディストリビューションサーバー (1 台または複数) の設定

en: Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
ja: 使用する各ディストリビューションサーバーの名前空間 (Galaxy、プライベート Automation Hub、Red Hat Automation Hub) を取得します。

en: Get an API token for each distribution server you want to use.
ja: 使用するディストリビューションサーバーごとに API トークンを取得します。

en: Specify the API token for each distribution server you want to use.
ja: 使用するディストリビューションサーバーごとに API トークンを指定します。

en: Getting a namespace
ja: 名前空間の取得

en: You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
ja: コレクションをアップロードするには、Galaxy および/または Automation Hub の名前空間が必要です。名前空間を取得するには、以下を行います。

en: For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
ja: Galaxy の詳細は、Galaxy ドキュメントの「`Galaxy 名前空間 <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_」を参照してください。

en: For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
ja: Automation Hub の場合は、`Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_ を参照してください。

en: Getting your API token
ja: API トークンの取得

en: You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
ja: コレクションをアップロードするには、Galaxy や Automation Hub の API トークンが必要です。API トークンを使用してディストリビューションサーバーへの接続の認証を行い、コンテンツを保護します。

en: To get your API token:
ja: API トークンを取得するには、以下を行います。

en: For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
ja: Galaxy の場合は、`Galaxy プロファイルの設定 <https://galaxy.ansible.com/me/preferences>`_ ページに移動し、:guilabel:`API Key` をクリックします。

en: For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
ja: Automation Hub の場合は、`トークンページ <https://cloud.redhat.com/ansible/automation-hub/token/>`_ に移動し、:guilabel:`Load token` をクリックします。

en: Specifying your API token
ja: API トークンの指定

en: Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
ja: API トークンを取得したら、2 つの方法でディストリビューションサーバーごとに正しいトークンを指定できます。

en: Pass the token to  the ``ansible-galaxy`` command using the ``--token``.
ja: ``--token`` を使用して、トークンを ``ansible-galaxy`` コマンドに渡します。

en: Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
ja: :file:`ansible.cfg` ファイルの Galaxy サーバーリストにトークンを構成します。

en: Specifying your API token with the ``--token`` argument
ja: ``--token`` 引数での API トークンの指定

en: You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
ja: ``--token`` 引数は、``ansible-galaxy`` コマンド (:file:`ansible.cfg` ファイルの ``--server`` 引数または :ref:`GALAXY_SERVER` 設定とともに) で使用できます。:ref:`Galaxy サーバー一覧 <galaxy_server_config>` で定義されているサーバーでは、``apt-key`` を使用することはできません。

en: Specifying your API token with a Galaxy server list
ja: Galaxy サーバーリストで API トークンの指定

en: You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
ja: ``galaxy_server_list`` セクションの下にある :file:`ansible.cfg` で Galaxy 用に 1 つ以上のディストリビューションサーバーを構成します。サーバーごとに、トークンも構成します。

en: See :ref:`galaxy_server_config` for complete details.
ja: 詳細は、「:ref:`galaxy_server_config`」を参照してください。

en: Building a collection tarball
ja: コレクション tarball のビルド

en: Once you have configured one or more distribution servers, you must build a collection tarball. To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
ja: 1 つ以上のディストリビューションサーバーを設定したら、コレクション tarball を構築する必要があります。コレクションを構築するには、コレクションのルートディレクトリー内から ``ansible-galaxy collection build`` を実行します。

en: This creates a tarball of the built collection in the current directory which can be uploaded to your distribution server::
ja: これにより、現在のディレクトリーに構築されたコレクションの tarball が作成されます。これはディストリビューションサーバーにアップロードできます。

en: Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections`  to exclude other files you would not want to distribute.
ja: コレクションアーティファクトのビルド時に、特定のファイルおよびフォルダーは除外されます。配布したくない他のファイルを除外するには、「:ref:`ignoring_files_and_folders_collections`」を参照してください。

en: If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
ja: 今回の非推奨となった ``Mazer`` ツールをコレクションに使用した場合は、``ansible-galaxy`` でコレクションをビルドする前に、:file:`releases/` ディレクトリーに追加したすべてのファイルを削除します。

en: The current Galaxy maximum tarball size is 2 MB.
ja: 現在の Galaxy の tarball の最大サイズは 2 MB です。

en: This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems.
ja: この tarball は、配布方法として主に Galaxy にアップロードすることを目的としていますが、ターゲットシステムにコレクションをインストールするために直接使用することもできます。

en: Ignoring files and folders
ja: ファイルやフォルダーを無視する

en: By default the build step will include all the files in the collection directory in the final build artifact except for the following:
ja: デフォルトでは、ビルドステップには、以下を除き、最終的なビルドアーティファクト内のコレクションディレクトリーにあるすべてのファイルが含まれます。

en: previously built artifacts in the root directory
ja: ルートディレクトリーに以前にビルドされたアーティファクト

en: various version control directories like ``.git/``
ja: ``.git/`` などのさまざまなバージョン管理ディレクトリー

en: To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the ``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for wildcard matching:
ja: コレクションの構築時に他のファイルおよびディレクトリーを除外するには、コレクションの ``galaxy.yml`` ファイルの ``build_ignore`` キーに、ファイルグロブのようなパターンの一覧を設定します。これらのパターンはワイルドカードの一致に以下の特殊文字を使用します。

en: ``*``: Matches everything
ja: ``*``: すべてに一致します。

en: ``?``: Matches any single character
ja: ``?``: 任意の単一文字に一致します。

en: ``[seq]``: Matches and character in seq
ja: ``[seq]``: シーケンス内の文字に一致します。

en: ``[!seq]``:Matches any character not in seq
ja: ``[!seq]``: シーケンスにない文字と一致します。

en: For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you can set the following in your ``galaxy.yml`` file:
ja: たとえば、``playbooks`` ディレクトリー内の :file:`sensitive` ディレクトリーや ``.tar.gz`` アーカイブを除外する場合は、``galaxy.yml`` ファイルに以下を設定することができます。

en: This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
ja: この機能は、Ansible 2.10 以降と ``ansible-galaxy collection build`` を実行する場合に限りサポートされます。

en: Collection versions
ja: コレクションのバージョン

en: Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy or Automation Hub; however, users will still be able to download older versions.
ja: コレクションを公開するたびに、新しいバージョンを作成します。コレクションのバージョンを公開したら、そのバージョンを削除または変更することはできません。公開する前に、すべてが正常に見えることを確認してください。コレクションを変更する唯一の方法は、新しいバージョンをリリースすることです。(最大バージョン番号による) コレクションの最新バージョンは、Galaxy または Automation Hub のあらゆる場所に表示されるバージョンになります。ただし、ユーザーは引き続き古いバージョンをダウンロードできます。

en: Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
ja: コレクションのバージョンは、バージョン番号に `セマンティックバージョン <https://semver.org/>`_ を使用します。詳細と例は、公式ドキュメントをお読みください。要約すると、以下のようになります。

en: Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
ja: 互換性のない API 変更のメジャーバージョンのバージョン番号 (例: `x.y.z` の x) が増えていきます。

en: Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).
ja: 後方互換の方法で新機能のマイナーバージョンのバージョン番号 (例: `x.y.z` の y)(新しいモジュール/プラグイン、パラメーター、戻り値など) が増えていきます。

en: Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
ja: 後方互換のバグ修正向けのパッチのバージョン番号 (例: `x.y.z` の z) が増えていきます。

en: Trying collections locally
ja: ローカルでコレクションを試行

en: Before you publish your collection, test it out locally. Every time you publish a tarball, you create a :ref:`new version <collection_versions>` of your collection. Testing the collection locally gives you confidence that the new version will contain the functionality you want without unexpected behavior.
ja: コレクションをパブリッシュする前にローカルからテストします。tarball を公開する際に、:ref:`新しいバージョン <collection_versions>` のコレクションを作成します。コレクションをローカルでテストすることで、新しいバージョンに、予期しない動作のない機能が含まれることを示します。

en: Trying your collection from the tarball
ja: tarball からコレクションを試してください。

en: You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:
ja: コレクションを tarball からインストールすることで、コレクションをローカルで試すことができます。以下では、隣接用の Playbook がコレクションにアクセスできるようになります。

en: You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install`` installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``.
ja: パスのために、:ref:`COLLECTIONS_PATHS` で構成された値の 1 つを使用する必要があります。これは、Ansible 自体がコレクションを使用しようとしたときにコレクションを見つけることを期待する場所でもあります。パス値を指定しない場合、``ansible-galaxy collection install`` は、:ref:`COLLECTIONS_PATHS` で定義された最初のパスにコレクションをインストールします。このデフォルトは、``~/.ansible/collections`` となります。

en: If you want to use a collection directly out of a checked out git repository, see :ref:`hacking_collections`.
ja: 確認された git リポジトリーから直接コレクションを使用する場合は、「:ref:`hacking_collections`」を参照してください。

en: Next, try using the local collection inside a playbook. For examples and more details see :ref:`Using collections <using_collections>`
ja: 次に、Playbook 内でローカルコレクションの使用を試行します。例および詳細は、「:ref:`コレクションの使用 <using_collections>`」を参照してください。

en: Trying your collection from a git repository
ja: git リポジトリーからのコレクションの試行

en: You can also test a version of your collection in development by installing it from a git repository.
ja: また、Git リポジトリーからインストールすることで、開発でコレクションのバージョンをテストすることもできます。

en: You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a ``tar.gz`` file. The collection must contain a ``galaxy.yml`` or ``MANIFEST.json`` file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with ``git+`` (or with ``git@`` to use a private repository with ssh authentication) and optionally supports a comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ version (for example, a commit or tag).
ja: コレクション名または ``tar.gz`` ファイルへのパスではなく、リポジトリーに URI を提供することにより、git リポジトリーにコレクションをインストールできます。コレクションには、``galaxy.yml`` ファイルまたは ``MANIFEST.json`` ファイルが必要です。このコレクションは、ディレクトリーからコレクションになる予定のアーティファクトデータを生成するのに使用されます。URI のプレフィックスには ``git+`` (または ssh 認証でプライベートリポジトリーを使用する ``git@``) を付け、必要に応じてコンマ区切りの `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ バージョン (コミットまたはタグなど) をサポートする必要があります。

en: Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs.
ja: 認証情報を git URI に埋め込むことは安全ではありません。セキュリティー上の理由から、安全な認証オプションを使用してください。たとえば、Git 設定の `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_、`netrc <https://linux.die.net/man/5/netrc>`_、または `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ で、クレジットがログに公開されないようにします。

en: In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in addition to using the ``git+repo,version`` syntax for the collection name.
ja: ``requirements.yml`` ファイルでは、コレクション名の ``git+repo,version`` 構文を使用する他に、``type`` キーおよび ``version`` キーを使用することもできます。

en: Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts.
ja: git リポジトリーはコレクションの依存関係にも使用できます。これは、ローカル開発およびテストに役立ちますが、ビルド/公開されたアーティファクトには他のアーティファクトへの依存関係のみが必要です。

en: Default repository search locations
ja: デフォルトのリポジトリー検索の場所

en: There are two paths searched in a repository for collections by default.
ja: デフォルトでは、コレクション用のリポジトリーで 2 つのパスが検索されます。

en: The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository path. If the file exists it's used as the collection metadata and the individual collection will be installed.
ja: 1 つ目は、リポジトリーパスのトップレベルにある ``galaxy.yml`` ファイルまたは ``MANIFEST.json`` ファイルです。ファイルが存在する場合は、コレクションのメタデータとして使用され、個々のコレクションがインストールされます。

en: The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection.
ja: 2 つ目は、リポジトリーパス (1 レベルの深さ) の各ディレクトリーの ``galaxy.yml`` ファイルまたは ``MANIFEST.json`` ファイルです。ここでは、メタデータファイルが含まれる各ディレクトリーがコレクションとしてインストールされます)。

en: Specifying the location to search for collections
ja: コレクションを検索する場所の指定

en: If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a ``galaxy.yml`` file or ``MANIFEST.json`` file).
ja: 異なるリポジトリー構造がある場合や、コレクションのサブセットのみをインストールする場合は、URI の最後にフラグメントを追加して (任意のコンマ区切りバージョンの前)、ansible-galaxy がメタデータファイルを調べるパスを示すことができます。パスは、(``MANIFEST.json`` ファイルまたは ``galaxy.yml`` ファイルへのパスではなく) コレクションまたは複数のコレクションへのディレクトリーである必要があります。

en: Publishing a collection
ja: コレクションの公開

en: Once you have a namespace and an API token for each distribution server you want to use, and you have created and tested a collection tarball, you can distribute your collection by publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
ja: 使用する各ディストリビューションサーバーの名前空間および API トークンがあり、コレクションの tarball を作成し、テストしたら、tarball を Ansible Galaxy、Red Hat Automation Hub、またはプライベートにホストする Automation Hub インスタンスに公開して、コレクションを配布することができます。``ansible-galaxy collection publish`` コマンドまたはディストリビューションサーバー (Galaxy、Automation Hub) のいずれかを使用できます。

en: Each time you add features or make changes to your collection, you must create a new collection artifact and publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
ja: 機能を追加したり、コレクションに変更を加えるたびに、新しいコレクションアーティファクトを作成し、コレクションの新しいバージョンを公開する必要があります。バージョンの詳細は、「:ref:`collection_versions`」を参照してください。

en: Publish a collection using ``ansible-galaxy``
ja: ``ansible-galaxy`` を使用してコレクションを公開します。

en: By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
ja: デフォルトでは、``ansible-galaxy`` は、(:ref:`galaxy_server` の下の :file:`ansible.cfg` ファイルに記載されるように) https://galaxy.ansible.com を Galaxy サーバーとして使用します。コレクションのみを Ansible Galaxy に公開している場合、追加設定は必要ありません。Red Hat Automation Hub またはその他の Galaxy サーバーを使用している場合は、「:ref:`ansible-galaxy クライアントの設定 <galaxy_server_config>`」を参照してください。

en: To upload the collection artifact with the ``ansible-galaxy`` command:
ja: ``ansible-galaxy`` コマンドでコレクションアーティファクトをアップロードするには、以下を使用します。

en: The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
ja: 上記のコマンドは、API トークンを取得して Galaxy サーバーリストの一部として取得し、保存していることを前提としています。詳細は「:ref:`galaxy_get_token`」を参照してください。

en: The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
ja: ``ansible-galaxy collection publish`` コマンドは、Galaxy の Web サイトでコレクションをアップロードしているのと同様に、インポートプロセスを発生させます。コマンドは、ステータスを報告する前にインポートプロセスが完了するまで待ちます。インポート結果を待たずに続行する場合は、``--no-wait`` 引数を使用して、`My Imports <https://galaxy.ansible.com/my-imports/>`_ ページで手動でインポートの進行状況を確認します。

en: Publishing a collection using the Galaxy website
ja: Galaxy Web サイトを使用したコレクションの公開

en: To publish your collection directly on the Galaxy website:
ja: コレクションを Galaxy の Web サイトに直接公開するには、以下を実行します。

en: Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces.
ja: `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ ページに移動し、名前空間のいずれかの **コンテンツを追加** ボタンをクリックします。

en: From the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
ja: **コンテンツの追加** ダイアログから、**新規コレクションのアップロード** をクリックして、ローカルファイルシステムからコレクションのアーカイブファイルを選択します。

en: When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request will fail.
ja: コレクションをアップロードするときに、Web サイトで選択した名前空間に関係なく、``galaxy.yml`` ファイルにあるコレクションメタデータで指定された名前空間にアップロードしてください。コレクションメタデータで指定された名前空間の所有者でない場合、アップロードリクエストは失敗します。

en: Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection.
ja: Galaxy がコレクションをアップロードして受け入れると、**My Imports** ページにリダイレクトされます。このページには、コレクションに含まれるメタデータやコンテンツに関するエラーや警告など、インポート処理の出力が表示されます。

en: Migrating Ansible content to a different collection
ja: Ansible コンテンツのコレクションへの移行

en: When you move content from one collection to another, for example to extract a set of related modules out of ``community.general`` to create a more focused collection, you must make sure the transition is easy for users to follow.
ja: あるコレクションから別のコレクションにコンテンツを移動する場合 (たとえば、関連するモジュールセットを ``community.general`` から抽出して、より重点的に集中化したコレクションを作成するには)、ユーザーが簡単に移行できるようにする必要があります。

en: Migrating content
ja: コンテンツの移行

en: Before you start migrating content from one collection to another, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
ja: あるコレクションから別のコレクションにコンテンツの移行を開始する前に、`Ansible コレクションチェックリスト <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_ を参照してください。

en: To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
ja: コレクションが `Ansible ディストリビューション <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_ の一部である場合は、コレクションを別のコレクションに移行するには、以下を実行します。

en: Copy content from the source (old) collection to the target (new) collection.
ja: ソース (以前の) コレクションからターゲット (新しい) コレクションにコンテンツをコピーします。

en: Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection.
ja: 古いコレクションの ``meta/runtime.yml`` の次のメジャーバージョンに予定されている ``removal_version`` でモジュール/プラグインが非推奨になりました。コピーされたコンテンツが新しいコレクションのリリースにあった後に、非推奨がリリースする必要があります。

en: When the next major release of the old collection is prepared:
ja: 古いコレクションの次のメジャーリリースが準備されている場合は、以下のようになります。

en: remove the module/plugin from the old collection
ja: 古いコレクションからモジュール/プラグインを削除する

en: remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)
ja: 必要に応じて、``plugin/modules`` ディレクトリーに保存されたシンボリックリンクを削除する (主に ``community.general`` および ``community.network``から削除する場合)。

en: remove related unit and integration tests
ja: 関連するユニットテストおよび統合テストを削除する

en: remove specific module utils
ja: 特定のモジュールユーティリティーを削除する

en: remove specific documentation fragments if there are any in the old collection
ja: 古いコレクションにある場合は、特定のドキュメントフラグメントを削除する

en: add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_
ja: ``removed_features`` および ``breaking_changes`` のエントリーを含む変更ログフラグメントを追加する。この `プル要求 <https://github.com/ansible-collections/community.general/pull/1304>`_ で変更ログフラグメントの例を確認できます。

en: change ``meta/runtime.yml`` in the old collection:
ja: 古いコレクションの ``meta/runtime.yml`` を変更する。

en: add ``redirect`` to the corresponding module/plugin's entry
ja: 対応するモジュール/プラグインのエントリーに ``redirect`` を追加する

en: in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable
ja: 特に、削除されたモジュールユーティリティーおよびドキュメントフラグメント (該当する場合) に ``redirect`` を追加する。

en: remove ``removal_version`` from there
ja: そこから ``removal_version`` を削除する。

en: remove related entries from ``tests/sanity/ignore.txt`` files if exist
ja: ``tests/sanity/ignore.txt`` ファイルから関連エントリーが存在する場合は削除する

en: remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)
ja: 変更ログの一部ではない削除されたコンテンツの変更ログフラグメントを削除する (つまり、`changelogs/changelog.yaml` を変更せず、そのファイルに記述されているファイルを削除しないでください)

en: remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml``
ja: ``tests/unit/requirements.txt``、``tests/requirements.yml``、および ``galaxy.yml`` ではなくなった要件を削除します。

en: To implement these changes, you need to create at least three PRs:
ja: 以下の変更を実装するには、少なくとも 3 つの PR を作成する必要があります。

en: Create a PR against the new collection to copy the content.
ja: 新しいコレクションに対して PR を作成し、コンテンツをコピーします。

en: Deprecate the module/plugin in the old collection.
ja: 古いコレクションのモジュール/プラグインが非推奨になります。

en: Later create a PR against the old collection to remove the content according to the schedule.
ja: 後に、古いコレクションに対して PR を作成し、スケジュールに応じてコンテンツを削除します。

en: Adding the content to the new collection
ja: 新しいコレクションへのコンテンツの追加

en: Create a PR in the new collection to:
ja: 新しいコレクションで PR を作成し、以下を行います。

en: Copy ALL the related files from the old collection.
ja: 古いコレクションから関連ファイルをすべてコピーします。

en: If it is an action plugin, include the corresponding module with documentation.
ja: アクションプラグインの場合は、対応するモジュールとドキュメントを含めます。

en: If it is a module, check if it has a corresponding action plugin that should move with it.
ja: モジュールの場合は、対応するアクションプラグインがあり、一緒に移動する必要があるかどうかを確認します。

en: Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
ja: ``meta/`` で、``runtime.yml`` に対する関連更新が存在する場合は、それを確認します。

en: Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
ja: 移動した ``tests/integration`` および ``tests/units`` を注意して確認し、FQCN を更新してください。

en: Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
ja: 古いコレクションの ``tests/sanity/ignore-*.txt`` エントリーを確認します。

en: Update ``meta/runtime.yml`` in the old collection.
ja: 古いコレクションの ``meta/runtime.yml`` を更新します。

en: Removing the content from the old collection
ja: 古いコレクションからのコンテンツの削除

en: Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
ja: ソースコレクションリポジトリーに対して PR を作成し、この移行に関連するモジュール、モジュールユーティリティー、プラグイン、およびドキュメントフラグメントを削除します。

en: If you are removing an action plugin, remove the corresponding module that contains the documentation.
ja: アクションプラグインを削除する場合は、ドキュメントが含まれる対応するモジュールを削除します。

en: If you are removing a module, remove any corresponding action plugin that should stay with it.
ja: モジュールを削除する場合は、モジュールに対応するアクションプラグインを削除してください。

en: Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
ja: 削除されたプラグインに関するエントリーを ``meta/runtime.yml`` から削除します。それらが新しいリポジトリーに追加されるようにしてください。

en: Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
ja: ``tests/sanity/ignore\*.txt`` から、sanity ignore (健常性の無視) の行を削除します。

en: Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
ja: 関連する統合テストを ``tests/units/plugins/`` から削除し、``tests/integrations/targets/`` およびユニットテストから削除します。

en: if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
ja: ``community.general`` または ``community.network`` からコンテンツを削除すると、``.github/BOTMETA.yml`` からエントリーを削除します。

en: Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
ja: 特定の非推奨のエントリーで削除または更新が必要になる可能性のあるエントリーについては、``meta/runtime.yml`` を慎重に確認してください。

en: Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
ja: ``meta/runtime.yml`` を更新して、新しいコレクション名を示す EVERY PLUGIN のリダイレクトを追加します。

en: Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
ja: 古いコレクションのメンテナーは、PR がユーザーエクスペリエンスとセマンティックバージョニングを壊さない方法でマージされるようにする必要があります。

en: A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
ja: マージされた PR を含む新しいバージョンは、コンテンツが移動されたコレクションが再びリリースされる前にリリースされてはならず、そのコンテンツが含まれています。そうしないと、リダイレクトが機能せず、そのコンテンツに依存している場合は破損が発生する可能性があります。

en: Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
ja: コンテンツが削除されたコレクションで 1.0.0 がリリースされると、この PR は新しい **メジャー** バージョン (つまり 2.0.0、3.0.0 など) のみをマージできます。

en: Updating BOTMETA.yml
ja: BOTMETA.yml の更新

en: The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
ja: ``BOTMETA.yml`` (たとえば `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_) は、以下の信頼できるソースです。

en: If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
ja: 古いコレクションまたは新しいコレクションで ``ansibullbot`` がある場合は、それに応じて ``BOTMETA.yml`` を更新する必要があります。

en: Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build process for docs.ansible.com will know where to find the module docs.
ja: Ansibulbot は、既存の問題と PR を新しいリポジトリーにリダイレクトする方法を認識します。docs.ansible.com のビルドプロセスは、モジュール文書の検索場所を認識します。

en: The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs.
ja: ``migrated_to:`` キーは、*ファイル* ごとに明示的に追加する必要があります。ディレクトリーレベルで ``migrated_to`` を追加することはできません。モジュールとプラグインの Web ドキュメントを新しいコレクションにリダイレクトすることです。

en: ``migrated_to:`` MUST be added for every:
ja: 以下のすべてに ``migrated_to:`` を追加する必要があります。

en: module
ja: モジュール

en: plugin
ja: プラグイン

en: module_utils
ja: モジュールユーティリティー

en: contrib/inventory script
ja: contrib/inventory スクリプト

en: You do NOT need to add ``migrated_to`` for:
ja: 以下に ``migrated_to`` を追加する必要はありません。

en: Unit tests
ja: ユニットテスト

en: Integration tests
ja: 統合テスト

en: ReStructured Text docs (anything under ``docs/docsite/rst/``)
ja: 再構築されたテキストドキュメント (``docs/docsite/rst/`` の下すべて)

en: Files that never existed in ``ansible/ansible:devel``
ja: ``ansible/ansible:devel`` に存在しないファイル

en: Using shared resources in collections
ja: コレクションで共有リソースの使用

en: Although developing Ansible modules contained in collections is similar to developing standalone Ansible modules, you use shared resources like documentation fragments and module utilities differently in collections. You can use documentation fragments within and across collections. You can use optional module utilities to support multiple versions of ansible-core in your collection.
ja: コレクションに含まれる Ansible モジュールの開発はスタンドアロンの Ansible モジュールの開発に似ていますが、コレクションではドキュメントフラグメントやモジュールユーティリティーなどの共有リソースを異なる方法で使用します。コレクション内およびコレクション間でドキュメントフラグメントを使用できます。任意のモジュールユーティリティーを使用して、コレクション内の複数のバージョンの ansible-core をサポートできます。

en: Using documentation fragments in collections
ja: コレクションでのドキュメントフラグメントの使用

en: To include documentation fragments in your collection:
ja: コレクションにドキュメントフラグメントを含めるには、以下を行います。

en: Create the documentation fragment: ``plugins/doc_fragments/fragment_name``.
ja: ドキュメントフラグメントを作成します (``plugins/doc_fragments/fragment_name``)。

en: Refer to the documentation fragment with its FQCN.
ja: FQCN を含むドキュメントフラグメントを参照してください。

en: :ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes.core <https://github.com/ansible-collections/kubernetes.core>`_ collection includes a complete example.
ja: :ref:`module_docs_fragments` は、ドキュメントフラグメントの基本を説明します。`kubernetes.core <https://github.com/ansible-collections/kubernetes.core>`_コレクションには完全な例が含まれています。

en: If you use FQCN, you can use documentation fragments from one collection in another collection.
ja: FQCN を使用する場合は、別のコレクションで 1 つのコレクションからドキュメントフラグメントを使用できます。

en: Leveraging optional module utilities in collections
ja: コレクションでの任意のモジュールユーティリティーの活用

en: Optional module utilities let you adopt the latest features from the most recent ansible-core release in your collection-based modules without breaking your collection on older Ansible versions. With optional module utilities, you can leverage the latest features when running against the latest versions, while still providing fallback behaviors when running against older versions.
ja: 任意のモジュールユーティリティーを使用すると、古い Ansible バージョンのコレクションを壊すことなく、collection-base モジュールで最新の ansible-core リリースの最新機能を採用できます。任意のモジュールユーティリティーを使用すると、最新バージョンに対して実行する場合に最新の機能を利用でき、古いバージョンに対して実行する場合でもフォールバック動作を提供できます。

en: This implementation, widely used in Python programming, wraps optional imports in conditionals or defensive `try/except` blocks, and implements fallback behaviors for missing imports. Ansible's module payload builder supports these patterns by treating any module_utils import nested in a block (e.g., `if`, `try`) as optional. If the requested import cannot be found during the payload build, it is simply omitted from the target payload and assumed that the importing code will handle its absence at runtime. Missing top-level imports of module_utils packages (imports that are not wrapped in a block statement of any kind) will fail the module payload build, and will not execute on the target.
ja: この実装は Python プログラミングで広く使用され、条件または限定された `try/except` ブロックで任意のインポートをラップし、不足しているインポートのフォールバック動作を実装します。Ansible のモジュールペイロードビルダーは、ブロックでネストされた module_utils インポート (例: `if`、`try`) をオプションとして扱うことにより、これらのパターンをサポートします。ペイロードビルド時に要求されたインポートが見つからなかった場合、これはターゲットペイロードから省略され、インポートコードがランタイム時に処理されないことが仮定されます。module_utils パッケージのトップレベルのインポート (あらゆる種類のブロックステートメントでラップされていないインポート) はモジュールペイロードビルドに失敗し、ターゲットでは実行されません。

en: For example, the `ansible.module_utils.common.respawn` package is only available in Ansible 2.11 and higher. The following module code would fail during the payload build on Ansible 2.10 or earlier (as the requested Python module does not exist, and is not wrapped in a block to signal to the payload builder that it can be omitted from the module payload):
ja: たとえば、`ansible.module_utils.common.respawn` パッケージは Ansible 2.11 以降でしか利用することができません。以下のモジュールコードは Ansible 2.10 以前でのペイロードビルド中に失敗します (要求された Python モジュールが存在せず、モジュールペイロードから省略できることをペイロードビルダーに通知するブロックにラップされていないため)。

en: By wrapping the import statement in a ``try`` block, the payload builder will omit the Python module if it cannot be located, and assume that the Ansible module will handle it at runtime:
ja: ``try`` ブロックで import ステートメントをラップすることで、ペイロードビルダーは、Python モジュールが見つからないと Python モジュールを省略し、Ansible モジュールがランタイム時に処理することを想定します。

en: The optional import behavior also applies to module_utils imported from collections.
ja: 任意のインポート動作は、コレクションからインポートされたモジュールユーティリティーにも適用されます。

en: Collection structure
ja: コレクション構造

en: A collection is a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. A collection does require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy and other tools need in order to package, build and publish the collection.
ja: コレクションは簡単なデータ構造です。それらの中の 1 つに属する特定のコンテンツがない限り、ディレクトリーは必要ありません。コレクションのルートレベルで ``galaxy.yml`` ファイルが必要になります。このファイルには、Galaxy やその他のツールがコレクションをパッケージ化、ビルド、公開するのに必要なメタデータがすべて含まれます。

en: Collection directories and files
ja: コレクションディレクトリーおよびファイル

en: A collection can contain these directories and files::
ja: コレクションには、これらのディレクトリーおよびファイルを含めることができます。

en: Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :file:`/docs` folder.
ja: Ansible は、:file:`README` ファイルおよび :file:`/docs` フォルダー内のすべてのファイルの ``.md`` 拡張子のみを受け入れます。

en: See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for examples of collection structure.
ja: コレクション構造の例は、`ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org を参照してください。

en: Not all directories are currently in use. Those are placeholders for future features.
ja: 現在、すべてのディレクトリーが使用されているわけではありません。これらは、将来の機能のプレースホルダーです。

en: A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact. See :ref:`collections_galaxy_meta` for details.
ja: コレクションには、コレクションアーティファクトを構築するために必要な情報が含まれる ``galaxy.yml`` ファイルが必要です。詳細は、「:ref:`collections_galaxy_meta`」を参照してください。

en: docs directory
ja: docs ディレクトリー

en: Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders.
ja: このディレクトリーに、コレクションに関する一般的なドキュメントを追加します。Python ドキュメント文字列として埋め込まれたプラグインおよびモジュールに関する特定のドキュメントを保持します。``docs`` フォルダーを使用して、コレクションが提供するロールおよびプラグイン、ロール要件などを説明します。マークダウンを使用し、サブフォルダーを追加しないでください。

en: Use ``ansible-doc`` to view documentation for plugins inside a collection:
ja: ``ansible-doc`` を使用して、コレクション内のプラグインのドキュメントを表示します。

en: The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace.
ja: 特定のプラグインのドキュメントを表示するには、``ansible-doc`` コマンドに完全修飾コレクション名 (FQCN) が必要です。この例では、``my_namespace`` は Galaxy 名前空間となり、``my_collection`` はその名前空間内のコレクション名となります。

en: The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name.
ja: Ansible コレクションの Galaxy 名前空間は ``galaxy.yml`` ファイルで定義されます。GitHub の組織またはリポジトリー名とは異なる場合があります。

en: plugins directory
ja: plugins ディレクトリー

en: Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play.
ja: 「プラグインタイプごと」の特有サブディレクトリーをここに追加します。これには、その FQCN を使用して、モジュールでだけでなくほとんどのプラグインで使用できる ``module_utils`` が含まれます。これは、すべてのプレイでロールをインポートすることなくモジュール、検索、フィルターなどを分散する方法です。

en: Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
ja: コレクションでは、vars プラグインはサポートされていません。cache プラグインはファクトキャッシュのためにコレクションで使用できますが、inventory プラグインではサポートされていません。

en: When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``
ja: コレクションで ``module_utils`` を使用してコーディングする場合、Python の ``import`` ステートメントは ``ansible_collections`` 規則とともに FQCN を考慮する必要があります。作成される Python インポートは ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}`` のようになります。

en: The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``. In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is ``community.test_collection.plugins.module_utils.qradar``:
ja: 以下のスニペットの例は、デフォルトの Ansible ``module_utils`` と、コレクションの両方を使用する Python および PowerShell モジュールを示しています。この例では、名前空間は ``community`` で、コレクションは ``test_collection`` です。Python の例では、問題の ``module_util`` は ``qradar`` と呼ばれ、FQCN が ``community.test_collection.plugins.module_utils.qradar`` となっています。

en: Note that importing something from an ``__init__.py`` file requires using the file name:
ja: ``__init__.py`` ファイルから何かをインポートする場合は、ファイル名を使用する必要があることに注意してください。

en: In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FQCN is ``community.test_collection.plugins.module_utils.hyperv``:
ja: PowerShell の例では、問題の ``module_util`` は ``hyperv`` と呼ばれ、FQCN が ``community.test_collection.plugins.module_utils.hyperv`` となっています。

en: roles directory
ja: roles ディレクトリー

en: Collection roles are mostly the same as existing roles, but with a couple of limitations:
ja: コレクションロールは既存ロールとほぼ同じですが、いくつか制限があります。

en: Role names are now limited to contain only lowercase alphanumeric characters, plus ``_`` and start with an alpha character.
ja: ロール名は、小文字の英数字と ``_`` のみを含み、英字で開始するように制限されます。

en: Roles in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection.
ja: コレクション内のロールにはプラグインを含めることができません。プラグインはコレクションの ``plugins`` ディレクトリーツリーで持続する必要があります。各プラグインはコレクション内のすべてのロールからアクセスできます。

en: The directory name of the role is used as the role name. Therefore, the directory name must comply with the above role name rules. The collection import into Galaxy will fail if a role name does not comply with these rules.
ja: ロールのディレクトリー名はロール名として使用されます。そのため、ディレクトリー名は上記のロール名ルールに従う必要があります。Galaxy へのコレクションのインポートは、ロール名がこれらのルールに準拠していないと失敗します。

en: You can migrate 'traditional roles' into a collection but they must follow the rules above. You may need to rename roles if they don't conform. You will have to move or link any role-based plugins to the collection specific directories.
ja: 「従来のロール」をコレクションに移行できますが、上記のルールに従う必要があります。遵守していない場合は、ロールの名前を変更しなければならない場合もあります。ロールベースのプラグインをコレクション固有のディレクトリーに移動するか、リンクする必要があります。

en: For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` value in the role's metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a collection, Galaxy uses the role directory as the name of the role and ignores the ``role_name`` metadata value.
ja: ロールが GitHub リポジトリーから Galaxy に直接インポートされた場合は、ロールのメタデータに ``role_name`` 値を設定すると、Galaxy が使用するロール名が上書きされます。コレクションの場合、この値は無視されます。コレクションをインポートすると、Galaxy はロールディレクトリーをロール名として使用し、``role_name`` メタデータの値を無視します。

en: playbooks directory
ja: playbooks ディレクトリー

en: TBD.
ja: 現在準備中です。

en: tests directory
ja: tests ディレクトリー

en: Ansible Collections are tested much like Ansible itself, by using the `ansible-test` utility which is released as part of Ansible, version 2.9.0 and newer. Because Ansible Collections are tested using the same tooling as Ansible itself, via `ansible-test`, all Ansible developer documentation for testing is applicable for authoring Collections Tests with one key concept to keep in mind.
ja: Ansible Collection は、Ansible 自体と同じように、Ansible バージョン 2.9.0 以降に同梱される `ansible-test` ユーティリティーを使用してテストされます。Ansible コレクションは Ansible 自体と同じツールを使用してテストされるため、`ansible-test` を介して、テスト用のすべての Ansible 開発者向けドキュメントは、覚えておくべき 1 つの重要な概念を使用してコレクションテストを作成するために適用できます。

en: See :ref:`testing_collections` for specific information on how to test collections with ``ansible-test``.
ja: ``ansible-test`` でコレクションをテストする方法は、「:ref:`testing_collections`」を参照してください。

en: When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code via a git clone, which is typical of an Ansible developer. However, it's not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you.
ja: :ref:`developing_testing` のドキュメントを読む際、Ansible 開発者の典型的な git clone を使用して、ソースコードから Ansible を実行するコンテンツがあります。ただし、Ansible Collection の作成者がソースから Ansible を実行することは常に一般的ではなく、安定したリリースからではなく、コレクションを作成するには、ソースから Ansible を実行する必要はありません。そのため、`ansible-test` バイナリーパス、コマンド補完、または環境変数については、:ref:`developing_testing` ドキュメントで提示されます。Ansible Collection Testing ではこれが必要ありません。`ansible-test` を含む Ansible の安定したリリースをインストールするには、これらをセットアップすることが予想されるためです。

en: meta directory
ja: meta ディレクトリー

en: A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:
ja: コレクションは、コレクションの ``meta`` ディレクトリーの ``runtime.yml`` ファイルに追加のメタデータを保存できます。``runtime.yml`` ファイルは、最上位のキーをサポートします。

en: The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
ja: コレクションを使用するために必要な Ansible のバージョン。複数のバージョンはコンマで区切ることができます。

en: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
ja: バージョンは `PEP440 バージョン指定子 <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ ですが、内部では、Ansible はプレリリースセグメントを Ansible バージョンから切り捨てることにより、PEP440 の動作から逸脱しています。これは、Ansible2.11.0b1 が ``requires_ansible: ">=2.11"`` であるものと互換性があることを意味します。

en: Content in a collection that Ansible needs to load from another location or that has been deprecated/removed. The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys. To define a new location for a plugin, set the ``redirect`` field to another name. To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date.
ja: Ansible が別の場所から読み込む必要があるコレクション内のコンテンツ、もしくは非推奨となったか削除されるコレクションのコンテンツ。``plugin_routing`` の最上位のキーはプラグインのタイプで、個々のプラグイン名をサブキーとして使用します。プラグインの新しい場所を定義するには、``redirect`` フィールドを別の名前に設定します。プラグインを非推奨にするには、``deprecation`` フィールドを使用してカスタム警告メッセージと削除バージョンまたは日付を指定します。プラグインの名前が変更するか新しい場所に移動する場合は、``redirect`` フィールドも入力する必要があります。プラグインが完全に削除される場合、``tombstone`` は致命的なエラーメッセージ、および削除バージョンまたは日付に使用できます。

en: A mapping of names for Python import statements and their redirected locations.
ja: Python インポートステートメントの名前とそのリダイレクトされた場所のマッピング。

en: Learn how to package and publish your collection
ja: コレクションをパッケージ化し、公開する方法を説明します。

en: Testing collections
ja: コレクションのテスト

en: Testing your collection ensures that your code works well and integrates well with the rest of the Ansible ecosystem. Your collection should pass the general compile and sanity tests for Ansible code. You should also add unit tests to cover the code in your collection and integration tests to cover the interactions between your collection and ansible-core.
ja: コレクションのテストにより、コードが適切に機能し、Ansible エコシステムの他の部分との統合性が向上します。コレクションでは、Ansible コードの一般的なコンパイルおよび健全性テストを渡します。また、コレクションのコードに対応するユニットテストと、コレクションと ansible-core との間の対話に対応する統合テストを追加する必要があります。

en: Testing tools
ja: テストツール

en: The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
ja: コレクションをテストする主なツールは、:ref:`developing_testing` に記載されている Ansible のテストツールである ``ansible-test`` です。また、複数のコンパイルチェックと健全性チェックを実行したり、``ansible-test`` を使用してプラグイン用にユニットテストや統合テストを実行できます。コレクションをテストする場合に、使用する ansible-core バージョンに対してテストすることができます。

en: You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Azure Pipelines both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
ja: 常に、コレクションのルートディレクトリーから、``ansible-test`` を実行する必要があります。特別な要件をインストールせずに Docker コンテナーの ``ansible-test`` を実行できます。Ansible チームは、ansible/ansible GitHub リポジトリーと、`community.general <https://github.com/ansible-collections/community.general/>`_ や `community.network <https://github.com/ansible-collections/community.network/>`_ ような大規模なコミュニティーコレクションの両方の Azure Pipeline で、このアプローチを使用します。以下の例では、Docker コンテナーでテストの実行方法を示しています。

en: Compile and sanity tests
ja: コンパイルと健全性テスト

en: To run all compile and sanity tests::
ja: すべてのコンパイルおよび健全性テストを実行するには、以下を実行します。

en: See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues.
ja: 詳細は、:ref:`testing_compile` および :ref:`testing_sanity` を参照してください。健全性テストの詳細と、特定された問題を修正する方法は、「:ref:`健全性テストの完全リスト <all_sanity_tests>`」を参照してください。

en: Adding unit tests
ja: ユニットテストの追加

en: You must place unit tests in the appropriate ``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
ja: ユニットテストを適切な ``tests/unit/plugins/`` ディレクトリーに置く必要があります。たとえば、``tests/unit/plugins/module_utils/foo/test_bar.py`` または ``tests/unit/plugins/module_utils/foo/bar/test_bar.py`` の ``plugins/module_utils/foo/bar.py`` にテストを置きます。たとえば、`unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_ を参照してください。

en: To run all unit tests for all supported Python versions::
ja: サポートされるすべての Python バージョンに対して、すべてのユニットテストを実行するには、以下のコマンドを実行します。

en: To run all unit tests only for a specific Python version::
ja: 特定の Python バージョンに対してのみ、ユニットテストをすべて実行するには、以下を実行します。

en: To run only a specific unit test::
ja: 特定のユニットテストのみを実行するには、以下を実行します。

en: You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files.
ja: ``tests/unit/requirements.txt`` ファイルで Python 要件を指定できます。詳細 (特にフィクスチャーファイルの詳細) は、「:ref:`testing_units`」を参照してください。

en: Adding integration tests
ja: 統合テストの追加

en: You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on.
ja: 統合テストは、適切な ``tests/integration/targets/`` ディレクトリーに置く必要があります。モジュールの統合テストでは、モジュール名だけを使用することができます。たとえば、``plugins/modules/foo.py`` の統合テストを ``tests/integration/targets/foo/`` というディレクトリーに置くことになります。モジュール以外のプラグインの統合テストでは、ディレクトリー名にプラグインタイプを追加する必要があります。たとえば、``plugins/connections/bar.py`` の統合テストは、``tests/integration/targets/connection_bar/`` というディレクトリーに置くことになります。たとえば、ルックアッププラグインの場合、ディレクトリー名は ``lookup_foo`` となり、インベントリプラグインの場合は、``inventory_foo`` となります。

en: You can write two different kinds of integration tests:
ja: 2 種類の統合テストを作成できます。

en: Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services.
ja: Ansible ロールテストは、``ansible-playbook`` で実行され、モジュールのさまざまな側面を検証します。これらのテストは、他の統合テスト (通常 ``prepare_bar`` または ``setup_bar`` と呼ばれ、モジュール ``foo`` をテストするためにサービスを準備したり、``bar`` という要件をインストールしたりする) に依存して、必要なライブラリーのインストールやサーバーサービスの設定など、必要なリソースを設定することができます。

en: ``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings.
ja: ``runme.sh`` テストは、直接スクリプトとして実行されます。インベントリーファイルを設定し、さまざまな設定で ``ansible-playbook`` または ``ansible-inventory`` を実行できます。

en: For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details.
ja: 例については、「`community.general の統合テスト <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_」を参照してください。詳細は、「:ref:`testing_integration`」も参照してください。

en: Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
ja: 統合テストは、要件のインストールや、サービスの設定、開始、および停止を行うことができるため、可能な限り、Docker コンテナーや、制限された環境で実行することが推奨されます。デフォルトでは、``ansible-test`` は複数のオペレーティングシステムの Docker イメージをサポートします。すべてのオプションは `サポート対象の docker イメージ <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ を参照してください。クラウドモジュール用などのプラットフォームに依存しない統合テストには、主に ``default`` イメージを使用します。以下の例では、``centos8`` イメージが使用されています。

en: To execute all integration tests for a collection::
ja: コレクションに対して統合テストをすべて実行するには、次を実行します。

en: If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
ja: より詳細な出力が必要な場合は、``-v`` ではなく、``-vvv`` でコマンドを実行します。もしくは、``--retry-on-error`` を指定して、失敗したテストを、詳細レベルをあげて自動的に再実行します。

en: To execute only the integration tests in a specific directory::
ja: 特定のディレクトリーで統合テストのみを実行するには、以下を行います。

en: You can specify multiple target names. Each target name is the name of a directory in ``tests/integration/targets/``.
ja: 複数のターゲット名を指定できます。ターゲット名は ``tests/integration/targets/`` のディレクトリーの名前になります。

en: More resources on testing Ansible
ja: Ansible のテストに関するその他のリソース

en: Developing ``ansible-core``
ja: ``ansible-core`` の開発

en: Although ``ansible-core`` (the code hosted in the `ansible/ansible repository <https://github.com/ansible/ansible>`_ on GitHub) includes a few plugins that can be swapped out via playbook directives or configuration, much of the code there is not modular.  The documents here give insight into how the parts of ``ansible-core`` work together.
ja: ``ansible-core`` (GitHub の `ansible/ansible repository <https://github.com/ansible/ansible>`_ でホストされるコード) には、Playbook ディレクティブまたは設定を介してスワップできるプラグインが含まれていますが、モジュール化されないコードが多くあります。また、``ansible-core`` の一部が連携する方法に関するドキュメントです。

en: Learn about the Python API for task execution
ja: タスク実行用の Python API について

en: Learn about developing plugins
ja: プラグインの開発について

en: #ansible-devel IRC chat channel
ja: IRC チャットチャンネル (#ansible-devel)

en: Developing dynamic inventory
ja: 動的インベントリーの開発

en: Ansible can pull inventory information from dynamic sources, including cloud sources, by using the supplied :ref:`inventory plugins <inventory_plugins>`. For details about how to pull inventory information, see :ref:`dynamic_inventory`. If the source you want is not currently covered by existing plugins, you can create your own inventory plugin as with any other plugin type.
ja: Ansible は、指定された :ref:`インベントリープラグイン <inventory_plugins>` を使用して、クラウドソースを含む動的ソースからインベントリー情報をプルすることができます。インベントリー情報のプル方法の詳細は、「:ref:`dynamic_inventory`」を参照してください。現在、既存のプラグインで対象としていないソースについては、他のプラグインタイプで独自のインベントリープラグインを作成できます。

en: In previous versions, you had to create a script or program that could output JSON in the correct format when invoked with the proper arguments. You can still use and write inventory scripts, as we ensured backwards compatibility via the :ref:`script inventory plugin <script_inventory>` and there is no restriction on the programming language used. If you choose to write a script, however, you will need to implement some features yourself such as caching, configuration management, dynamic variable and group composition, and so on. If you use :ref:`inventory plugins <inventory_plugins>` instead, you can leverage the Ansible codebase and add these common features automatically.
ja: 以前のバージョンでは、適切な引数で呼び出されたときに正しい形式で JSON を出力できるスクリプトやプログラムを作成する必要がありました。:ref:`スクリプトインベントリープラグイン <script_inventory>` を通じて後方互換性を確保しており、使用するプログラミング言語にも制限がないため、インベントリースクリプトを使用したり書いたりすることができます。ただし、スクリプトを書く場合は、キャッシュ、設定管理、動的な変数、グループの構成など、いくつかの機能を自分で実装する必要があります。代わりに:ref:`インベントリープラグイン <inventory_plugins>` を使用すれば、Ansible のコードベースを活用し、これらの共通機能を自動的に追加することができます。

en: Inventory sources
ja: インベントリーソース

en: Inventory sources are the input strings that inventory plugins work with. An inventory source can be a path to a file or to a script, or it can be raw data that the plugin can interpret.
ja: インベントリーソースは、インベントリープラグインが機能する入力文字列です。インベントリーソースはファイルまたはスクリプトへのパスにするか、プラグインが解釈できる生のデータになります。

en: The table below shows some examples of inventory plugins and the source types that you can pass to them with ``-i`` on the command line.
ja: 以下の表は、コマンドラインで ``-i`` を使用して、インベントリープラグインの例と、プラグインに渡すことができるソースタイプを示しています。

en: Plugin
ja: プラグイン

en: Source
ja: ソース

en: A comma-separated list of hosts
ja: ホストのコンマ区切りリスト

en: Path to a YAML format data file
ja: YAML 形式のデータファイルへのパス

en: Path to a YAML configuration file
ja: YAML 設定ファイルへのパス

en: Path to an INI formatted data file
ja: INI 形式のデータファイルへのパス

en: Path to an executable that outputs JSON
ja: JSON を出力する実行可能ファイルへのパス

en: Inventory plugins
ja: Inventory プラグイン

en: Like most plugin types (except modules), inventory plugins must be developed in Python. They execute on the controller and should therefore adhere to the :ref:`control_node_requirements`.
ja: ほとんどのプラグインタイプ (モジュールを除く) と同様に、それらは Python で開発されなければなりません。コントローラー上で実行するため、「:ref:`control_node_requirements`」と同じ要件に一致させなければなりません。

en: Most of the documentation in :ref:`developing_plugins` also applies here. You should read that document first for a general understanding and then come back to this document for specifics on inventory plugins.
ja: :ref:`developing_plugins` に関するドキュメントの多くはここでも適用されています。一般的な理解のために最初にこのドキュメントを読んでから、本ガイドで inventory プラグインの詳細を参照してください。

en: Normally, inventory plugins are executed at the start of a run, and before the playbooks, plays, or roles are loaded. However, you can use the ``meta: refresh_inventory`` task to clear the current inventory and execute the inventory plugins again, and this task will generate a new inventory.
ja: 通常、インベントリープラグインは実行の開始時、および Playbook、プレイ、またはロールが読み込まれる前に実行します。ただし、``meta: refresh_inventory`` タスクを使用して現在のインベントリーを消去してインベントリープラグインを再実行することもできます。また、このタスクは新しいインベントリーを生成します。

en: If you use the persistent cache, inventory plugins can also use the configured cache plugin to store and retrieve data. Caching inventory avoids making repeated and costly external calls.
ja: 永続キャッシュを使用する場合、inventory プラグインは設定済みのキャッシュプラグインを使用してデータを保存および取得し、コストがかかり、繰り返しかかる外部呼び出しを回避することもできます。

en: Developing an inventory plugin
ja: inventory プラグインの開発

en: The first thing you want to do is use the base class:
ja: 最初に行うのは、ベースクラスを使用することです。

en: If the inventory plugin is in a collection, the NAME should be in the 'namespace.collection_name.myplugin' format. The base class has a couple of methods that each plugin should implement and a few helpers for parsing the inventory source and updating the inventory.
ja: inventory プラグインがコレクションにある場合、NAME は「namespace.collection_name.myplugin」形式である必要があります。このベースクラスは、各プラグインが実装する必要のあるいくつかのメソッドと、インベントリーソースを解析してインベントリーを更新するためのヘルパーがいくつかあります。

en: After you have the basic plugin working, you can incorporate other features by adding more base classes:
ja: 基本的なプラグインが動作するようになったら、より多くの基本クラスを追加することで他の機能を組み込むことができます。

en: For the bulk of the work in a plugin, we mostly want to deal with 2 methods ``verify_file`` and ``parse``.
ja: プラグインでの作業の大部分では、主に 2 つのメソッド (``verify_file`` と ``parse``) を扱います。

en: verify_file method
ja: verify_file メソッド

en: Ansible uses this method to quickly determine if the inventory source is usable by the plugin. The determination does not need to be 100% accurate, as there might be an overlap in what plugins can handle and by default Ansible will try the enabled plugins as per their sequence.
ja: Ansible はこのメソッドを使用して、インベントリソースがプラグインで使用可能かどうかを迅速に判断します。この判定は 100％ 正確である必要はありません。なぜなら、プラグインが処理できる内容には重複があり、デフォルトでは Ansible は有効なプラグインを順番に試していくからです。

en: In the above example, from the :ref:`virtualbox inventory plugin <virtualbox_inventory>`, we screen for specific file name patterns to avoid attempting to consume any valid YAML file. You can add any type of condition here, but the most common one is 'extension matching'. If you implement extension matching for YAML configuration files, the path suffix <plugin_name>.<yml|yaml> should be accepted. All valid extensions should be documented in the plugin description.
ja: 上記の例では、:ref:`virtualbox インベントリープラグイン <virtualbox_inventory>` からは、有効な YAML ファイルの使用を試みないように、特定のファイル名パターンを切り分けます。ここに任意のタイプの条件を追加できますが、最も一般的なものは「拡張子の一致」です。YAML 設定ファイルに一致する拡張子を実装する場合は、パスサフィックス <plugin_name>.<yml|yaml> が許可される必要があります。有効なすべての拡張機能は、プラグインの説明に記載されています。

en: The following is another example that does not use a 'file' but the inventory source string itself, from the :ref:`host list <host_list_inventory>` plugin:
ja: 以下は、「ファイル」を使用せず、:ref:`host list <host_list_inventory>` プラグインからインベントリソース文字列自体を使用する別の例です。

en: This method is just to expedite the inventory process and avoid unnecessary parsing of sources that are easy to filter out before causing a parse error.
ja: この方法は、inventory プロセスを迅速化し、解析エラーの原因になる前に簡単に除外できるソースの不要な解析を回避するためのものです。

en: parse method
ja: 解析メソッド

en: This method does the bulk of the work in the plugin. It takes the following parameters:
ja: この方法は、プラグインの作業の大部分を行います。このメソッドは、以下のパラメーターを取ります。

en: inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory
ja: inventory: 既存のデータと、ホスト/グループ/変数をインベントリーに追加するメソッドがある inventory オブジェクト。

en: loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
ja: loader: Ansible の DataLoader です。DataLoader は、ファイルの読み取り、JSON/YAML の自動読み込み、vault を使用したデータの復号化、および読み取りファイルのキャッシュを行うことができます。

en: path: string with inventory source (this is usually a path, but is not required)
ja: path: インベントリーソースを持つ文字列 (通常、これはパスですが、必須ではありません)。

en: cache: indicates whether the plugin should use or avoid caches (cache plugin and/or loader)
ja: cache: プラグインがキャッシュを使用するかどうかを示します (キャッシュプラグインまたはローダー、もしくはその両方)。

en: The base class does some minimal assignment for reuse in other methods.
ja: ベースクラスは他のメソッドで再利用するための割り当てを最小限に抑えます。

en: It is up to the plugin now to parse the provided inventory source and translate it into Ansible inventory. To facilitate this, the example below uses a few helper functions:
ja: 提供されたインベントリーソースを解析し、それを Ansible インベントリーに変換するのは、プラグイン次第です。これを容易にするために、以下の例ではいくつかのヘルパー関数を使用しています。

en: The specifics will vary depending on API and structure returned. Remember that if you get an inventory source error or any other issue, you should ``raise AnsibleParserError`` to let Ansible know that the source was invalid or the process failed.
ja: この状況は、API および構造の戻り値によって異なります。インベントリーソースエラーや他の問題を取得する場合は、``AnsibleParserError を発生`` させ、ソースが無効であるか、プロセスが失敗したことを Ansible に通知する必要があります。

en: For examples on how to implement an inventory plugin, see the source code here: `lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_.
ja: インベントリープラグインの実装方法の例は、ソースコード (`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_) を参照してください。

en: inventory cache
ja: インベントリーキャッシュ

en: To cache the inventory, extend the inventory plugin documentation with the inventory_cache documentation fragment and use the Cacheable base class.
ja: インベントリーをキャッシュするには、インベントリープラグインのドキュメントを inventory_cache ドキュメントフラグメントで拡張し、Cacheable 基本クラスを使用します。

en: Next, load the cache plugin specified by the user to read from and update the cache. If your inventory plugin uses YAML-based configuration files and the ``_read_config_data`` method, the cache plugin is loaded within that method. If your inventory plugin does not use ``_read_config_data``, you must load the cache explicitly with ``load_cache_plugin``.
ja: 次に、ユーザーが指定したキャッシュプラグインを読み込み、キャッシュの読み取りと更新を行います。インベントリープラグインが YAML ベースの構成ファイルを使用していて、``_read_config_data`` メソッドの場合、キャッシュプラグインはそのメソッド内に読み込まれます。インベントリープラグインが ``_read_config_data`` を使用しない場合は、``load_cache_plugin`` を使用してキャッシュを明示的に読み込む必要があります。

en: Before using the cache plugin, you must retrieve a unique cache key by using the ``get_cache_key`` method. This task needs to be done by all inventory modules using the cache, so that you don't use/overwrite other parts of the cache.
ja: キャッシュプラグインを使用する前に、``get_cache_key`` メソッドを使用して一意のキャッシュキーを取得する必要があります。このタスクは、キャッシュを使用するすべてのインベントリーモジュールで実行する必要があります。これにより、キャッシュの他の部分を使用/上書きしないようになります。

en: Now that you've enabled caching, loaded the correct plugin, and retrieved a unique cache key, you can set up the flow of data between the cache and your inventory using the ``cache`` parameter of the ``parse`` method. This value comes from the inventory manager and indicates whether the inventory is being refreshed (such as via ``--flush-cache`` or the meta task ``refresh_inventory``). Although the cache shouldn't be used to populate the inventory when being refreshed, the cache should be updated with the new inventory if the user has enabled caching. You can use ``self._cache`` like a dictionary. The following pattern allows refreshing the inventory to work in conjunction with caching.
ja: これでキャッシュを有効にし、正しいプラグインを読み込み、一意のキャッシュキーを取得し、``parse`` メソッドの ``cache`` パラメーターを使用して、キャッシュとインベントリーの間でデータのフローを設定できるようになりました。この値は、インベントリーマネージャーから取得され、インベントリーを更新するか (例: ``--flush-cache``、メタタスク ``refresh_inventory`` など) を示します。キャッシュは、更新時にインベントリーを入力するために使用しますが、キャッシュを有効にした場合は、キャッシュを新しいインベントリーで更新する必要があります。ディクショナリーのような ``self._cache`` を使用できます。以下のパターンを使用すると、インベントリーをキャッシュとともに動作させることができます。

en: After the ``parse`` method is complete, the contents of ``self._cache`` is used to set the cache plugin if the contents of the cache have changed.
ja: ``parse`` メソッドが完了すると、``self._cache`` の内容は、キャッシュの内容が変更された場合にキャッシュプラグインを設定するために使用されます。

en: You have three other cache methods available:
ja: 3 つのキャッシュメソッドが利用できます。

en: ``set_cache_plugin`` forces the cache plugin to be set with the contents of ``self._cache``, before the ``parse`` method completes
ja: ``set_cache_plugin`` は、``parse`` メソッドの完了前に、キャッシュプラグインを ``self._cache`` の内容で強制的に設定します。

en: ``update_cache_if_changed`` sets the cache plugin only if ``self._cache`` has been modified, before the ``parse`` method completes
ja: ``update_cache_if_changed`` は、``parse`` メソッドが完了する前に ``self._cache`` が変更された場合のみキャッシュプラグインを設定します。

en: ``clear_cache`` flushes the cache, ultimately by calling the cache plugin's ``flush()`` method, whose implementation is dependent upon the particular cache plugin in use. Note that if the user is using the same cache backend for facts and inventory, both will get flushed. To avoid this, the user can specify a distinct cache backend in their inventory plugin configuration.
ja: ``clear_cache`` キャッシュをフラッシュし、キャッシュプラグインの ``flush()`` メソッドを呼び出すことで、これらの実装は使用中の特定のキャッシュプラグインに依存します。ファクトとインベントリーで同じキャッシュバックエンドを使用している場合は、両方のキャッシュバックエンドをフラッシュします。これを回避するために、インベントリープラグイン設定で個別のキャッシュバックエンドを指定できます。

en: constructed features
ja: constructed 機能

en: Inventory plugins can create host variables and groups from Jinja2 expressions and variables by using features from the ``constructed`` inventory plugin. To do this, use the ``Constructable`` base class and extend the inventory plugin's documentation with the ``constructed`` documentation fragment.
ja: インベントリープラグインは、``constructed`` インベントリープラグインの機能を使用して、Jinja2 式および変数からホスト変数およびグループを作成できます。これを行うには、``Constructable`` ベースクラスを使用し、``constructed`` ドキュメントフラグメントでドキュメントを拡張することができます。

en: The three main options from the ``constructed`` documentation fragment are ``compose``, ``keyed_groups``, and ``groups``. See the ``constructed`` inventory plugin for examples on using these. ``compose`` is a dictionary of variable names and Jinja2 expressions. Once a host is added to inventory and any initial variables have been set, call the method ``_set_composite_vars`` to add composed host variables. If this is done before adding ``keyed_groups`` and ``groups``, the group generation will be able to use the composed variables.
ja: ``constructed`` ドキュメントフラグの 3 つの主要なオプションは、``compose``、``keyed_groups``、および ``groups`` です。これらの使用例は、``constructed`` インベントリープラグインを参照してください。``compose`` は、変数名および Jinja2 式のディクショナリーです。ホストがインベントリーに追加され、初期変数が設定されると、``_set_composite_vars`` メソッドを呼び出して構成されたホスト変数を追加します。``keyed_groups`` および ``groups`` を追加する前にこれを行うと、グループの生成は構成された変数を使用できます。

en: By default, group names created with ``_add_host_to_composed_groups()`` and ``_add_host_to_keyed_groups()`` are valid Python identifiers. Invalid characters are replaced with an underscore ``_``. A plugin can change the sanitization used for the constructed features by setting ``self._sanitize_group_name`` to a new function. The core engine also does sanitization, so if the custom function is less strict it should be used in conjunction with the configuration setting ``TRANSFORM_INVALID_GROUP_CHARS``.
ja: デフォルトでは、``_add_host_to_composed_groups()`` および ``_add_host_to_keyed_groups()`` で作成されたグループ名は有効な Python 識別子です。無効な文字はアンダースコア ``_`` に置き換えられます。プラグインは、``self._sanitize_group_name`` を新しい機能に設定することで、constructed 機能に使用されるサニタイゼーションを変更できます。コアエンジンもサニタイゼーションを実行するため、カスタム機能がそれほど厳密でない場合は、構成設定 ``TRANSFORM_INVALID_GROUP_CHARS`` と組み合わせて使用する必要があります。

en: Common format for inventory sources
ja: インベントリーソースの共通形式

en: To simplify development, most plugins use a standard YAML-based configuration file as the inventory source. The file has only one required field ``plugin``, which should contain the name of the plugin that is expected to consume the file. Depending on other common features used, you might need other fields, and you can add custom options in each plugin as required. For example, if you use the integrated caching, ``cache_plugin``, ``cache_timeout`` and other cache-related fields could be present.
ja: 開発を簡単にするために、ほとんどのプラグインはインベントリーソースとして標準的な YAML ベースの設定ファイルを使用しています。このファイルには、必須フィールドが 1 つしかありません (``plugin``)。このフィールドには、このファイルを使用することが期待されるプラグインの名前を入れる必要があります。使用する他の共通機能によっては、他のフィールドが必要になる場合があり、必要に応じて各プラグインにカスタムオプションを追加することができます。たとえば、統合キャッシングを使用する場合は、``cache_plugin``、``cache_timeout`` などのキャッシュ関連のフィールドが存在する可能性があります。

en: The 'auto' plugin
ja: 「auto」プラグイン

en: From Ansible 2.5 onwards, we include the :ref:`auto inventory plugin <auto_inventory>` and enable it by default. If the ``plugin`` field in your standard configuration file matches the name of your inventory plugin, the ``auto`` inventory plugin will load your plugin. The 'auto' plugin makes it easier to use your plugin without having to update configurations.
ja: Ansible 2.5 以降では、:ref:`auto inventory plugin <auto_inventory>` を追加し、これをデフォルトで有効化します。標準設定ファイルの ``plugin`` フィールドがインベントリープラグインの名前と一致する場合、``auto`` インベントリープラグインはプラグインを読み込みます。「auto」プラグインは、設定を更新せずにプラグインを簡単に使用できます。

en: Inventory scripts
ja: インベントリースクリプト

en: Even though we now have inventory plugins, we still support inventory scripts, not only for backwards compatibility but also to allow users to leverage other programming languages.
ja: inventory プラグインはそのままですが、後方互換性だけでなく、ユーザーが他のプログラミング言語を使用できるように、引き続きインベントリースクリプトをサポートします。

en: Inventory script conventions
ja: インベントリースクリプトの規則

en: Inventory scripts must accept the ``--list`` and ``--host <hostname>`` arguments. Although other arguments are allowed, Ansible will not use them. Such arguments might still be useful for executing the scripts directly.
ja: インベントリースクリプトでは、引数 ``--list`` および ``--host <hostname>`` を使用する必要があります。他の引数は設定できますが、Ansible はそれらを使用しません。このような引数は、スクリプトを直接実行するのに役立つ場合があります。

en: When the script is called with the single argument ``--list``, the script must output to stdout a JSON object that contains all the groups to be managed. Each group's value should be either an object containing a list of each host, any child groups, and potential group variables, or simply a list of hosts::
ja: スクリプトが単一の引数 ``--list`` で呼び出されると、スクリプトは、標準出力に、管理するすべてのグループが含まれる JSON オブジェクトを出力する必要があります。各グループの値は、各ホスト、子グループ、および潜在的なグループ変数の一覧を含むオブジェクト、または簡単にホストの一覧にする必要があります。

en: If any of the elements of a group are empty, they may be omitted from the output.
ja: グループのいずれかの要素が空の場合は、出力から省略される可能性があります。

en: When called with the argument ``--host <hostname>`` (where <hostname> is a host from above), the script must print a JSON object, either empty or containing variables to make them available to templates and playbooks. For example::
ja: 引数 ``--host <hostname>`` で呼び出される場合 (<hostname> は上記のホスト) で呼び出されると、スクリプトは、空か、変数を含む JSON オブジェクトを出力して、テンプレートと Playbook で利用可能にする必要があります。以下に例を示します。

en: Printing variables is optional. If the script does not print variables, it should print an empty JSON object.
ja: 変数の出力は任意です。スクリプトが変数を出力しない場合は、空の JSON オブジェクトを出力する必要があります。

en: Tuning the external inventory script
ja: 外部インベントリースクリプトのチューニング

en: The stock inventory script system mentioned above works for all versions of Ansible, but calling ``--host`` for every host can be rather inefficient, especially if it involves API calls to a remote subsystem.
ja: 上記のストックのインベントリースクリプトシステムは、すべてのバージョンの Ansible に対して動作しますが、特にリモートサブシステムへの API 呼び出しが必要になる場合は、すべてのホストに対して ``--host`` を呼び出すこともできます。

en: To avoid this inefficiency, if the inventory script returns a top-level element called "_meta", it is possible to return all the host variables in a single script execution. When this meta element contains a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host. This behavior results in a significant performance increase for large numbers of hosts.
ja: これを回避するには、インベントリースクリプトが「_meta」という最上位の要素を返す場合には、単一スクリプトの実行ですべてのホスト変数を返すことができます。このメタ要素に「hostvars」の値が含まれていると、インベントリースクリプトは各ホストに対して ``--host`` で呼び出されません。この動作は、多数のホストのパフォーマンスを大幅に向上します。

en: The data to be added to the top-level JSON object looks like this::
ja: レベルの JSON オブジェクトに追加するデータは次のようになります。

en: To satisfy the requirements of using ``_meta``, to prevent ansible from calling your inventory with ``--host`` you must at least populate ``_meta`` with an empty ``hostvars`` object. For example::
ja: Ansible が ``--host`` でインベントリーを呼び出すのを防ぐために ``_meta`` を使用する要件を満たすには、少なくとも空の ``hostvars`` オブジェクトで ``_meta`` を埋めなければなりません。以下に例を示します。

en: If you intend to replace an existing static inventory file with an inventory script, it must return a JSON object which contains an 'all' group that includes every host in the inventory as a member and every group in the inventory as a child. It should also include an 'ungrouped' group which contains all hosts which are not members of any other group. A skeleton example of this JSON object is:
ja: 既存の静的インベントリーファイルをインベントリースクリプトに置き換える場合は、インベントリー内のすべてのホストをメンバーとして、インベントリー内のすべてのグループを子として含む「すべて」のグループを含む JSON オブジェクトを返す必要があります。また、他のグループのメンバーではないすべてのホストを含む「グループ化されていない」グループも含める必要があります。この JSON オブジェクトのスケルトンの例は次のとおりです。

en: An easy way to see how this should look is using :ref:`ansible-inventory`, which also supports ``--list`` and ``--host`` parameters like an inventory script would.
ja: これがどのように見えるかを確認する簡単な方法は、:ref:`ansible-inventory` を使用することです。これにより、インベントリースクリプトのように ``--list`` パラメーターおよび ``--host`` パラメーターがサポートされます。

en: Python API to Playbooks and Ad Hoc Task Execution
ja: Playbook およびアドホックタスク実行のための Python API

en: Get started with developing a module
ja: モジュールの開発を始める

en: REST API endpoint and GUI for Ansible, syncs with dynamic inventory
ja: Ansible の REST API エンドポイントおよび GUI (動的インベントリーと同期)

en: Adding modules and plugins locally
ja: モジュールおよびプラグインをローカルで追加

en: The easiest, quickest, and the most popular way to extend Ansible is to use a local module or a plugin. You can create them or copy existing ones for local use. You can store a local module or plugin on your Ansible control node and share it with your team or organization. You can also share a local plugin or module by including it in a collection or embedding it in a role, then publishing the collection or role on Ansible Galaxy. If you are using roles on Ansible Galaxy, then you are already using local modules and plugins without realizing it.
ja: Ansible を拡張する最も簡単な方法は、ローカルモジュールまたはプラグインを使用することです。ローカルで使用するためにこれらを作成するか、既存のものをコピーすることができます。Ansible コントロールノードにローカルモジュールまたはプラグインを保存し、チームまたは組織と共有することができます。また、ローカルプラグインまたはモジュールをコレクションに含めるか、ロールに埋め込むことで、Ansible Galaxy にコレクションまたはロールを公開することもできます。Ansible Galaxy でロールを使用している場合は、認識せずにローカルモジュールとプラグインをすでに使用していることになります。

en: If you are using an existing module or plugin but Ansible can't find it, this page is all you need. However, if you want to create a plugin or a module, go to :ref:`developing_plugins` and :ref:`developing_modules_general` topics and then return to this page to know how to add it locally.
ja: 既存のモジュールまたはプラグインを使用しているにもかかわらず、Ansible で見つからない場合は、このページのみが必要となります。プラグインまたはモジュールを作成する場合は、:ref:`developing_plugins` および :ref:`developing_modules_general` のトピックに移動してから、このページに戻り、ローカルで追加する方法を説明します。

en: Extending Ansible with local modules and plugins offers lots of shortcuts such as:
ja: ローカルのモジュールおよびプラグインで Ansible を拡張すると、以下のようなショートカットが多数利用できるようになります。

en: You can copy other people's modules and plugins.
ja: 他のユーザーのモジュールおよびプラグインをコピーできます。

en: When writing a new module, you can choose any programming language you like.
ja: 新しいモジュールを作成する場合は、任意のプログラミング言語を選択できます。

en: You do not have to clone any repositories.
ja: リポジトリーのクローンを作成する必要はありません。

en: You do not have to open a pull request.
ja: プル要求を開く必要はありません。

en: You do not have to add tests (though we recommend that you do!).
ja: テストを追加する必要はありません (ただし、この操作を推奨しています)。

en: To save a local module or plugin such that Ansible can find and use it, add the module or plugin in the appropriate directory (the directories are specified in later parts of this topic).
ja: Ansible が検出して使用するようにローカルモジュールまたはプラグインを保存するには、適切なディレクトリーにモジュールまたはプラグインを追加します (ディレクトリーは、本トピックの後半で指定されています)。

en: Modules and plugins: what is the difference?
ja: モジュールおよびプラグイン: 相違点

en: If you are looking to add local functionality to Ansible, you might wonder whether you need a module or a plugin. Here is a quick overview to help you decide between the two:
ja: Ansible にローカル機能を追加する場合は、モジュールまたはプラグインのいずれかが必要かを熟知している必要があります。以下は、モジュールまたはプラグインのどちらに問題があるかを判断するための簡単な概要です。

en: Modules are reusable, standalone scripts that can be used by the Ansible API, the :command:`ansible` command, or the :command:`ansible-playbook` command. Modules provide a defined interface. Each module accepts arguments and returns information to Ansible by printing a JSON string to stdout before exiting. Modules execute on the target system (usually that means on a remote system) in separate processes.
ja: モジュールは、Ansible API、:command:`ansible` コマンド、または :command:`ansible-playbook` コマンドで使用できる再利用可能なスタンドアロンスクリプトです。モジュールは、定義されたインターフェースを提供します。各モジュールは引数を受け入れ、終了する前に JSON 文字列を stdout に出力して Ansible に情報を返します。モジュールは、別のプロセスでターゲットシステム (通常はリモートシステム上) で実行されます。

en: :ref:`Plugins <plugins_lookup>` augment Ansible's core functionality and execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more.
ja: :ref:`プラグイン <plugins_lookup>` は、Ansible のコア機能を拡張し、``/usr/bin/ansible`` プロセス内のコントロールノードで実行します。プラグインは、Ansible のコア機能のオプションおよび拡張機能 (データの変換、ログ出力、インベントリーへの接続など) を提供します。

en: Adding a module locally
ja: モジュールをローカルで追加

en: Ansible automatically loads all executable files found in certain directories as modules.
ja: Ansible は、特定のディレクトリーにある実行可能ファイルをすべてモジュールとして自動的に読み込みます。

en: For local modules, use the name of the file as the module name: for example, if the module file is ``~/.ansible/plugins/modules/local_users.py``, use ``local_users`` as the module name.
ja: ローカルモジュールの場合は、ファイル名をモジュール名として使用します。たとえば、モジュールファイルが ``~/.ansible/plugins/modules/local_users.py`` の場合は、モジュール名として ``local_users`` を使用します。

en: To load your local modules automatically and make them available to all playbooks and roles, add them in any of these locations:
ja: ローカルモジュールを自動的に読み込み、すべての Playbook およびロールで使用できるようにするには、それらを以下のいずれかの場所に追加します。

en: any directory added to the ``ANSIBLE_LIBRARY`` environment variable (``$ANSIBLE_LIBRARY`` takes a colon-separated list like ``$PATH``)
ja: ``ANSIBLE_LIBRARY`` 環境変数に追加されたディレクトリー (``$ANSIBLE_LIBRARY`` は ``$PATH``のようにコロンで区切った一覧)

en: After you save your module file in one of these locations, Ansible loads it and you can use it in any local task, playbook, or role.
ja: モジュールファイルをこのいずれかの場所に保存すると、Ansible はそのファイルを読み込み、ローカルのタスク、Playbook、またはロールで使用できます。

en: To confirm that ``my_custom_module`` is available:
ja: ``my_custom_module`` が利用できることを確認するには、以下を行います。

en: type ``ansible localhost -m my_custom_module``. You should see the output for that module.
ja: ``ansible localhost -m my_custom_module`` を入力します。このモジュールの出力が表示されるはずです。

en: or
ja: または

en: type ``ansible-doc -t module my_custom_module``. You should see the documentation for that module.
ja: ``ansible-doc -t module my_custom_module`` を入力します。そのモジュールのドキュメントが表示されるはずです。

en: Currently, the ``ansible-doc`` command can parse module documentation only from modules written in Python. If you have a module written in a programming language other than Python, please write the documentation in a Python file adjacent to the module file.
ja: 現在、``ansible-doc`` コマンドは、Python で記述されたモジュールからのみモジュールドキュメントを解析できます。Python 以外のプログラミング言語で記述されたモジュールがある場合は、モジュールファイルの横の Python ファイルにドキュメントを作成してください。

en: You can limit the availability of your local module. If you want to use a local module only with selected playbooks or only with a single role, load it in one of the following locations:
ja: ローカルモジュールの可用性を制限することができます。選択した Playbook でのみローカルモジュールを使用する場合、または単一のロールでのみローカルモジュールを使用する場合は、以下のいずれかの場所にロードします。

en: In a selected playbook or playbooks: Store the module in a subdirectory called ``library`` in the directory that contains those playbooks.
ja: 選択した Playbook で、それらの Playbook が含まれるディレクトリーの ``library`` という名前のサブディレクトリーにモジュールを保存します。

en: In a single role: Store the module in a subdirectory called ``library`` within that role.
ja: 単一のロール: そのロール内の ``library`` という名前のサブディレクトリーにモジュールを保存します。

en: Adding a plugin locally
ja: プラグインをローカルで追加

en: Ansible loads plugins automatically too, and loads each type of plugin separately from a directory named for the type of plugin. Here's the full list of plugin directory names:
ja: Ansible はプラグインも自動的に読み込んで、プラグインのタイプに対して名前が付けられたディレクトリーとは別に、各タイプのプラグインを読み込みます。プラグインディレクトリー名の全一覧を以下に示します。

en: After you add the plugins and verify that they are available for use, you can see the documentation for all the plugins except for the ones marked with an asterisk (*) above.
ja: プラグインを追加して、それらが使用できることを確認すると、上記のアスタリスク (*) のマークが付いたものを除き、すべてのプラグインのドキュメントを表示できます。

en: To load your local plugins automatically, add them in any of these locations:
ja: ローカルプラグインを自動的に読み込むには、以下のいずれかの場所に追加します。

en: any directory added to the relevant ``ANSIBLE_plugin_type_PLUGINS`` environment variable (these variables, such as ``$ANSIBLE_INVENTORY_PLUGINS`` and ``$ANSIBLE_VARS_PLUGINS`` take colon-separated lists like ``$PATH``)
ja: 関連する ``ANSIBLE_plugin_type_PLUGINS`` 環境変数に追加されたディレクトリー (``$ANSIBLE_INVENTORY_PLUGINS``、``$ANSIBLE_VARS_PLUGINS`` などの、``$PATH`` のようにコロンで区切った一覧を取る変数)。

en: the directory named for the correct ``plugin_type`` within ``~/.ansible/plugins/`` - for example, ``~/.ansible/plugins/callback``
ja: ``~/.ansible/plugins/`` 内の正しい ``plugin_type`` という名前のディレクトリー (例: ``~/.ansible/plugins/callback``)

en: the directory named for the correct ``plugin_type`` within ``/usr/local/share/py38-ansible/plugins/`` - for example, ``/usr/local/share/py38-ansible/plugins/action``
ja: ``/usr/local/share/py38-ansible/plugins/`` 内の正しい ``plugin_type`` という名前のディレクトリー (例: ``/usr/local/share/py38-ansible/plugins/action``)

en: After your plugin file is in one of these locations, Ansible loads it and you can use it in any local module, task, playbook, or role. Alternatively, you can edit your ``ansible.cfg`` file to add directories that contain local plugins. For details about adding directories of local plugins, see :ref:`ansible_configuration_settings`.
ja: プラグインファイルがこれらの場所のいずれかに置かれたら、Ansible が読み込み、ローカルモジュール、タスク、Playbook、またはロールで使用することができます。``ansible.cfg`` ファイルを編集してローカルプラグインを含むディレクトリーを追加できます。ローカルプラグインのディレクトリーを追加する方法については、「:ref:`ansible_configuration_settings`」を参照してください。

en: To confirm that ``plugins/plugin_type/my_custom_plugin`` is available:
ja: ``plugins/plugin_type/my_custom_plugin`` が利用できることを確認するには、以下を行います。

en: type ``ansible-doc -t <plugin_type> my_custom_lookup_plugin``. For example, ``ansible-doc -t lookup my_custom_lookup_plugin``. You should see the documentation for that plugin. This works for all plugin types except the ones marked with ``*`` in the list above  - see :ref:`ansible-doc` for more details.
ja: ``ansible-doc -t <plugin_type> my_custom_lookup_plugin`` を入力します (例: ``ansible-doc -t lookup my_custom_lookup_plugin``)。そのプラグインに関するドキュメントを確認してください。これは上記のリストで ``*`` のマークが付いたもの以外のすべてのプラグインタイプで機能します。詳細は「:ref:`ansible-doc`」を参照してください。

en: You can limit the availability of your local plugin. If you want to use a local plugin only with selected playbooks or only with a single role, load it in one of the following locations:
ja: ローカルプラグインの可用性を制限することができます。選択した Playbook でのみローカルプラグインを使用する場合、または単一のロールでのみローカルプラグインを使用する場合は、以下のいずれかの場所に読み込みます。

en: In a selected playbook or playbooks: Store the plugin in a subdirectory for the correct ``plugin_type`` (for example, ``callback_plugins`` or ``inventory_plugins``) in the directory that contains the playbooks.
ja: 選択した Playbook: そのPlaybook を含むディレクトリーに、正しい ``plugin_type`` (例: ``callback_plugins`` または ``inventory_plugins``) のサブディレクトリーにプラグインを保存します。

en: In a single role: Store the plugin in a subdirectory for the correct ``plugin_type`` (for example, ``cache_plugins`` or ``strategy_plugins``) within that role. When shipped as part of a role, the plugin is available as soon as the role is executed.
ja: 単一のロール: そのロール内で、正しい ``plugin_type`` （例： ``cache_plugins`` または ``strategy_plugins``) のサブディレクトリーにプラグインを保存します。ロールの一部として提供された場合は、ロールが実行されるとすぐにプラグインが利用可能になります。

en: Using and developing module utilities
ja: モジュールユーティリティーの使用および開発

en: Ansible provides a number of module utilities, or snippets of shared code, that provide helper functions you can use when developing your own modules. The ``basic.py`` module utility provides the main entry point for accessing the Ansible library, and all Python Ansible modules must import something from ``ansible.module_utils``. A common option is to import ``AnsibleModule``::
ja: Ansible は、独自のモジュール開発時に使用できるヘルパー関数を提供する多くのモジュールユーティリティー、または共有コードのスニペットを提供します。``basic.py`` モジュールユーティリティーは、Ansible ライブラリーにアクセスするためのメインのエントリーポイントを提供します。また、すべての Python Ansible モジュールは ``ansible.module_utils`` からインポートする必要があります。一般的なオプションでは、``AnsibleModule`` をインポートするのが一般的です。

en: The ``ansible.module_utils`` namespace is not a plain Python package: it is constructed dynamically for each task invocation, by extracting imports and resolving those matching the namespace against a :ref:`search path <ansible_search_path>` derived from the active configuration.
ja: ``ansible.module_utils`` 名前空間は単純な Python パッケージではありません。これは、インポートを抽出し、アクティブな設定から派生する :ref:`検索パス <ansible_search_path>` に対して一致する名前空間を解決することで、各タスク呼び出し用に動的に構築されます。

en: To reduce the maintenance burden in a collection or in local modules, you can extract duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this::
ja: コレクションまたはローカルモジュールのメンテナンス負荷を軽減するには、重複コードを 1 つ以上のモジュールユーティリティーに抽出してモジュールにインポートすることができます。たとえば、``my_shared_code`` ライブラリーをインポートする独自のカスタムモジュールがある場合は、これを、以下のように ``./module_utils/my_shared_code.py`` ファイルに配置できます。

en: When you run ``ansible-playbook``, Ansible will merge any files in your local ``module_utils`` directories into the ``ansible.module_utils`` namespace in the order defined by the :ref:`Ansible search path <ansible_search_path>`.
ja: ``ansible-playbook`` を実行すると、Ansible は :ref:`Ansible search path <ansible_search_path>` で定義されている順序でローカルの ``module_utils`` ディレクトリーのファイルを ``ansible.module_utils`` 名前空間にマージします。

en: Naming and finding module utilities
ja: モジュールユーティリティーの命名および検索

en: You can generally tell what a module utility does from its name and/or its location. Generic utilities (shared code used by many different kinds of modules) live in the main ansible/ansible codebase, in the ``common`` subdirectory or in the root directory of ``lib/ansible/module_utils``. Utilities used by a particular set of modules generally live in the same collection as those modules. For example:
ja: 通常、モジュールユーティリティーが名前やその場所から動作するようにできます。汎用ユーティリティー (さまざまな種類のモジュールで使用される共有コード) は、メインの ansible/ansible コードベースにあります。``common`` サブディレクトリー、または ``lib/ansible/module_utils`` のルートディレクトリーにあります。特定のモジュールセットで使用されるユーティリティーは、通常、それらのモジュールと同じコレクションに存在します。以下に例を示します。

en: ``lib/ansible/module_utils/urls.py`` contains shared code for parsing URLs
ja: ``lib/ansible/module_utils/urls.py`` は、URL を解析するための共有コードが含まれています。

en: ``openstack.cloud.plugins.module_utils.openstack.py`` contains utilities for modules that work with OpenStack instances
ja: ``openstack.cloud.plugins.module_utils.openstack.py`` には、OpenStack インスタンスと連携するモジュールのユーティリティーが含まれます。

en: ``ansible.netcommon.plugins.module_utils.network.common.config.py`` contains utility functions for use by networking modules
ja: ``ansible.netcommon.plugins.module_utils.network.common.config.py`` は、ネットワークモジュールによって使用される設定ユーティリティーの機能が含まれます。

en: Following this pattern with your own module utilities makes everything easy to find and use.
ja: このパターンを独自のモジュールユーティリティーで行うと、あらゆるものを見つけ、使用することが容易になります。

en: Standard module utilities
ja: 標準のモジュールユーティリティー

en: Ansible ships with an extensive library of ``module_utils`` files. You can find the module utility source code in the ``lib/ansible/module_utils`` directory under your main Ansible path. We describe the most widely used utilities below. For more details on any specific module utility, please see the `source code for module_utils <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils>`_.
ja: Ansible には、``module_utils`` ファイルの広範なライブラリーが含まれています。モジュールユーティリティーのソースコードは、メインの Ansible パス下の ``lib/ansible/module_utils`` ディレクトリーにあります。また、以下で最も広く使用されているユーティリティーが含まれています。特定のモジュールユーティリティーの詳細は、「`モジュールユーティリティーのソースコード <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils>`_」を参照してください。

en: **LICENSING REQUIREMENTS**  Ansible enforces the following licensing requirements:
ja: **ライセンス要件** Ansible は、以下のライセンス要件を強制します。

en: Utilities (files in ``lib/ansible/module_utils/``) may have one of two licenses:
ja: ユーティリティー (``lib/ansible/module_utils/`` 内のファイル) には、2 つあるライセンスのいずれかが存在する可能性があります。

en: A file in ``module_utils`` used **only** for a specific vendor's hardware, provider, or service may be licensed under GPLv3+. Adding a new file under ``module_utils`` with GPLv3+ needs to be approved by the core team.
ja: 特定のベンダーのハードウェア、プロバイダー、またはサービスに**のみ** ``module_utils`` を使用するファイルは、GPLv3 以降でライセンスを取得している可能性があります。GPLv3 以降を持つ ``module_utils`` に新しいファイルを追加するには、コアチームによる承認が必要になります。

en: All other ``module_utils`` must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
ja: 他のすべての ``module_utils`` は、GPL のライセンスが付与されたサードパーティーと Galaxy モジュールが使用できるように、BSD でライセンスが付与されている必要があります。

en: If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible Core Team will decide during an Ansible Core Community Meeting.
ja: ``module_utils`` のファイルに適切なライセンスについて疑問がある場合は、Ansible Core Team が Ansible Core Community Meeting 中に決定します。

en: All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
ja: すべてのモジュールを含む Ansible に同梱される他のすべてのファイルは、GPL ライセンス (GPLv3 以降) でライセンスを取得する必要があります。

en: ``api.py`` - Supports generic API modules
ja: ``api.py`` - 汎用 API モジュールのサポート

en: ``basic.py`` - General definitions and helper utilities for Ansible modules
ja: ``basic.py`` - Ansible モジュールの一般的な定義およびヘルパーユーティリティー

en: ``common/dict_transformations.py`` - Helper functions for dictionary transformations
ja: ``common/dict_transformations.py`` - ディクショナリー変換のヘルパー関数

en: ``common/file.py`` - Helper functions for working with files
ja: ``common/file.py`` - ファイルを操作するヘルパー関数

en: ``common/text/`` - Helper functions for converting and formatting text
ja: ``common/text/`` - テキストの変換およびフォーマットを行うためのヘルパー関数

en: ``common/parameters.py`` - Helper functions for dealing with module parameters
ja: ``common/parameters.py`` - モジュールパラメーターを処理するヘルパー関数

en: ``common/sys_info.py`` - Functions for getting distribution and platform information
ja: ``common/sys_info.py`` - ディストリビューションおよびプラットフォーム情報を取得する機能

en: ``common/validation.py`` - Helper functions for validating module parameters against a module argument spec
ja: ``common/validation.py`` - モジュール引数仕様に対してモジュールパラメーターを検証するためのヘルパー関数

en: ``facts/`` - Directory of utilities for modules that return facts. See `PR 23012 <https://github.com/ansible/ansible/pull/23012>`_ for more information
ja: ``facts/`` - ファクトを返すモジュールのユーティリティーのディレクトリー。詳細は、`PR 23012 <https://github.com/ansible/ansible/pull/23012>`_ を参照してください。

en: ``json_utils.py`` - Utilities for filtering unrelated output around module JSON output, like leading and trailing lines
ja: ``json_utils.py`` - 先頭行や末尾行など、モジュール JSON 出力に関する関連のない出力をフィルターを設定するユーティリティー

en: ``powershell/`` - Directory of definitions and helper functions for Windows PowerShell modules
ja: ``powershell/`` - Windows PowerShell モジュールの定義およびヘルパー関数のディレクトリー

en: ``pycompat24.py`` - Exception workaround for Python 2.4
ja: ``pycompat24.py`` - Python 2.4 の例外回避策

en: ``service.py`` - Utilities to enable modules to work with Linux services (placeholder, not in use)
ja: ``service.py`` - モジュールが Linux サービスと連携できるようにするユーティリティー (未使用のプレースホルダー)

en: ``six/__init__.py`` - Bundled copy of the `Six Python library <https://pypi.org/project/six/>`_ to aid in writing code compatible with both Python 2 and Python 3
ja: ``six/__init__.py`` - Python 2 と Python 3 の両方と互換性のあるコードを書き込む際に助けとなる `Six Python ライブラリー <https://pypi.org/project/six/>`_ のバンドルコピー

en: ``splitter.py`` - String splitting and manipulation utilities for working with Jinja2 templates
ja: ``splitter.py`` - Jinja2 テンプレートを使用する文字列分割および操作ユーティリティー

en: ``urls.py`` - Utilities for working with http and https requests
ja: ``urls.py`` - http および https リクエストを操作するユーティリティー

en: Several commonly-used utilities migrated to collections in Ansible 2.10, including:
ja: 一般的に使用されるいくつかのユーティリティーは、Ansible 2.10 では以下のようなコレクションに移行されています。

en: ``ismount.py`` migrated to ``ansible.posix.plugins.module_utils.mount.py`` - Single helper function that fixes os.path.ismount
ja: ``ansible.posix.plugins.module_utils.mount.py`` に移行した ``ismount.py`` - os.path.ismount を修正する単一のヘルパー関数。

en: ``known_hosts.py`` migrated to ``community.general.plugins.module_utils.known_hosts.py`` - utilities for working with known_hosts file
ja: ``community.general.plugins.module_utils.known_hosts.py`` に移行した ``known_hosts.py`` - known_hosts ファイルで作業するためのユーティリティー

en: For a list of migrated content with destination collections, see https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml.
ja: 宛先コレクションで移行されたコンテンツの一覧は、https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml を参照してください。

en: Should you develop a module?
ja: モジュール開発の必要性

en: Developing Ansible modules is easy, but often it is not necessary. Before you start writing a new module, ask:
ja: Ansible モジュールの開発は容易ですが、通常は不要です。新しいモジュールを書き始める前に、以下を確認してください。

en: Does a similar module already exist?
ja: 同様のモジュールが存在しているか。

en: An existing module may cover the functionality you want. Ansible collections include thousands of modules. Search our :ref:`list of included collections <list_of_collections>` or `Ansible Galaxy <https://galaxy.ansible.com>`_ to see if an existing module does what you need.
ja: 既存のモジュールは必要な機能に対応できます。Ansible コレクションには、数千のモジュールが含まれています。:ref:`同梱されるコレクションの一覧 <list_of_collections>` または `Ansible Galaxy <https://galaxy.ansible.com>`_ を検索すると、既存のモジュールが必要なモジュールかどうかが分かります。

en: Should you use or develop an action plugin instead of a module?
ja: モジュールの代わりにアクションプラグインを使用するか、または開発する必要があるか。

en: An action plugin may be the best way to get the functionality you want. Action plugins run on the control node instead of on the managed node, and their functionality is available to all modules. For more information about developing plugins, read the :ref:`developing plugins page <developing_plugins>`.
ja: アクションプラグインは、必要な機能を取得する最善の方法となるでしょう。アクションプラグインは、管理ノードではなくコントロールノードで実行され、その機能はすべてのモジュールで利用できます。プラグインの開発に関する詳細は、「:ref:`プラグインの開発ページ<developing_plugins>`」を参照してください。

en: Should you use a role instead of a module?
ja: モジュールの代わりにロールを使用する必要があるか。

en: A combination of existing modules may cover the functionality you want. You can write a role for this type of use case. Check out the :ref:`roles documentation<playbooks_reuse_roles>`.
ja: 既存のモジュールの組み合わせによって、希望の機能に対応できる可能性があります。このタイプのユースケースにロールを作成することができます。「:ref:`ロールのドキュメント<playbooks_reuse_roles>`」を確認してください。

en: Should you create a collection instead of a single module?
ja: 1 つのモジュールの代わりにコレクションを作成する必要があるか。

en: The functionality you want may be too large for a single module. If you want to connect Ansible to a new cloud provider, database, or network platform, you may need to :ref:`develop a new collection<developing_modules_in_groups>`.
ja: 1 つのモジュールでは、この機能が大きすぎる可能性があります。Ansible を新しいクラウドプロバイダー、データベース、またはネットワークプラットフォームに接続する場合は、:ref:`新しいコレクションの開発<developing_modules_in_groups>` が必要になる場合があります。

en: Each module should have a concise and well defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
ja: 各モジュールには、簡潔で十分に機能が定義されている必要があります。基本的には、1 つのことを十分に行うという UNIX の哲学に従ってください。

en: A module should not require that a user know all the underlying options of an API/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected.
ja: モジュールは、使用する API またはツールの基礎となるすべてのオプションを把握する必要がありません。たとえば、必要なモジュールパラメーターの有効な値を文書化できない場合、それはモジュールが拒否されることを示しています。

en: Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API.
ja: モジュールは、通常、リソースと対話するロジックの多くを網羅する必要があります。ロジックをあまり含まない API の軽量ラッパーを使用すると、ユーザーがあまりにも多くのロジックを Playbook にオフロードする原因となる可能性があるため、モジュールが拒否されます。代わりに、API の小さな個々の部分と対話するための複数のモジュールを作成してみてください。

en: If your use case isn't covered by an existing module, an action plugin, or a role, and you don't need to create multiple modules, then you're ready to start developing a new module. Choose from the topics below for next steps:
ja: ユースケースが、既存のモジュール、アクションプラグイン、またはロールでは対応されておらず、複数のモジュールを作成する必要がない場合は、新しいモジュールの開発を開始する準備ができています。次のステップは、以下のトピックから選択します。

en: I want to :ref:`get started on a new module <developing_modules_general>`.
ja: :ref:`新しいモジュールを使用開始<developing_modules_general>` したいです。

en: I want to review :ref:`tips and conventions for developing good modules <developing_modules_best_practices>`.
ja: :ref:`良質なモジュールを開発するためのヒントおよび規約 <developing_modules_best_practices>` を確認します。

en: I want to :ref:`write a Windows module <developing_modules_general_windows>`.
ja: :ref:`Windows モジュールを作成 <developing_modules_general_windows>` したいです。

en: I want :ref:`an overview of Ansible's architecture <developing_program_flow_modules>`.
ja: :ref:`Ansible のアーキテクチャーの概要 <developing_program_flow_modules>` が必要です。

en: I want to :ref:`document my module <developing_modules_documenting>`.
ja: :ref:`作成したモジュールをドキュメント化 <developing_modules_documenting>` したいです。

en: I want to :ref:`contribute my module back to Ansible Core <developing_modules_checklist>`.
ja: :ref:`作成したモジュールを Ansible Core に貢献 <developing_modules_checklist>` したいです。

en: I want to :ref:`add unit and integration tests to my module <developing_testing>`.
ja: :ref:`作成したモジュールにユニットテストおよび統合テストを追加 <developing_testing>` したいです。

en: I want to :ref:`add Python 3 support to my module <developing_python_3>`.
ja: :ref:`作成したモジュールに Python 3 サポートを追加 <developing_python_3>` したいです。

en: I want to :ref:`write multiple modules <developing_modules_in_groups>`.
ja: :ref:`複数モジュールを作成 <developing_modules_in_groups>` したいです。

en: Browse existing collections, modules, and plugins
ja: 既存のコレクション、モジュール、およびプラグインの閲覧

en: Development mailing list
ja: 開発メーリングリスト

en: Conventions, tips, and pitfalls
ja: 規則、ヒント、および落とし穴

en: As you design and develop modules, follow these basic conventions and tips for clean, usable code:
ja: モジュールの設計および開発を行う際に、以下の基本的な規則およびヒントに従って、読みやすく使用可能なコードを作成します。

en: Scoping your module(s)
ja: モジュールのスコープ設定

en: Especially if you want to contribute your module(s) to an existing Ansible Collection, make sure each module includes enough logic and functionality, but not too much. If these guidelines seem confusing, consider :ref:`whether you really need to write a module <module_dev_should_you>` at all.
ja: 特に、既存の Ansible Collection にモジュールを提供する場合は、各モジュールに十分なロジックと機能が含まれていることを確認してください。ただし、多すぎないようにしてください。これらのガイドラインが紛らわしいと思われる場合は、:ref:`モジュールの記述が本当に必要かどうか <module_dev_should_you>` を検討してください。

en: Each module should have a concise and well-defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
ja: 各モジュールには、簡潔で十分に機能が定義されている必要があります。基本的には、1 つのことを十分に行うという UNIX の哲学に従ってください。

en: Do not add ``get``, ``list`` or ``info`` state options to an existing module - create a new ``_info`` or ``_facts`` module.
ja: 既存のモジュールに、``get``、``list``、または ``info`` の状態のオプションを追加しないでください。新しい ``_info`` モジュールまたは ``_facts`` モジュールを作成します。

en: Modules should not require that a user know all the underlying options of an API/tool to be used. For instance, if the legal values for a required module option cannot be documented, the module does not belong in Ansible Core.
ja: モジュールでは、使用する API またはツールの基礎となるオプションをすべてユーザーが把握する必要がありません。たとえば、必要なモジュールオプションの有効な値を文書化できない場合、そのモジュールは Ansible Core に属しません。

en: Modules should encompass much of the logic for interacting with a resource. A lightweight wrapper around a complex API forces users to offload too much logic into their playbooks. If you want to connect Ansible to a complex API, :ref:`create multiple modules <developing_modules_in_groups>` that interact with smaller individual pieces of the API.
ja: モジュールは、リソースと対話するためのロジックを多数組み込む必要があります。複雑な API に関連した軽量ラッパーにより、ユーザーは Playbook に非常に多くのロジックをオフロードします。Ansible を複雑な API に接続する場合は、API のより小さい個々の部分と対話する :ref:`複数のモジュールを作成 <developing_modules_in_groups>` します。

en: Avoid creating a module that does the work of other modules; this leads to code duplication and divergence, and makes things less uniform, unpredictable and harder to maintain. Modules should be the building blocks. If you are asking 'how can I have a module execute other modules' ... you want to write a role.
ja: 他のモジュールの作業を行うモジュールを作成しないようにしてください。これにより、コードの重複と差異が発生し、一貫性が保たれず、予測ができなくなり、維持が難しくなります。モジュールはビルディングブロックでなければなりません。「どのようにしてモジュールに他のモジュールを実行させることができるのか」という質問が浮かんでくる場合は、それがロールを作成する理由になります。

en: Designing module interfaces
ja: モジュールインターフェースの設計

en: If your module is addressing an object, the option for that object should be called ``name`` whenever possible, or accept ``name`` as an alias.
ja: モジュールがオブジェクトに対処している場合は、可能な限りそのオブジェクトのオプションを ``name`` とするか、またはエイリアスとして ``name`` を受け入れます。

en: Modules accepting boolean status should accept ``yes``, ``no``, ``true``, ``false``, or anything else a user may likely throw at them. The AnsibleModule common code supports this with ``type='bool'``.
ja: ブール値ステータスを許可するモジュールは、``yes``、``no``、``true``、``false``、もしくはユーザーに出力される可能性があるものはなんでも受け入れる必要がります。AnsibleModule の一般的なコードは、``type='bool'`` でこれをサポートします。

en: Avoid ``action``/``command``, they are imperative and not declarative, there are other ways to express the same thing.
ja: ``action``/``command`` は使用しないでください。これは命令型であり、宣言的ではありませんが、同じ方法を表示する方法は他にもあります。

en: General guidelines & tips
ja: 一般的なガイドラインおよびヒント

en: Each module should be self-contained in one file, so it can be auto-transferred by ``ansible-core``.
ja: 各モジュールは 1 つのファイルにまとめて自己完結させる必要があり、``ansible-core`` で自動転送できるようにします。

en: Module name MUST use underscores instead of hyphens or spaces as a word separator. Using hyphens and spaces will prevent ``ansible-core`` from importing your module.
ja: モジュール名は、単語の区切り文字として、ハイフンやスペースの代わりにアンダースコアを使用する必要があります。ハイフンやスペースを使用すると、``ansible-core`` がモジュールをインポートできなくなります。

en: Always use the ``hacking/test-module.py`` script when developing modules - it will warn you about common pitfalls.
ja: モジュールを開発する際には必ず ``hacking/test-module.py`` スクリプトを使用してください。よくある落とし穴について警告してくれます。

en: If you have a local module that returns information specific to your installations, a good name for this module is ``site_info``.
ja: インストールに固有の情報を返すローカルモジュールがある場合、このモジュールの適切な名前は ``site_info`` となります。

en: Eliminate or minimize dependencies. If your module has dependencies, document them at the top of the module file and raise JSON error messages when dependency import fails.
ja: 依存関係をなくするか、または最小限に抑えます。モジュールに依存関係がある場合は、モジュールファイルの冒頭で文書化し、依存関係のインポートに失敗した場合は JSON エラーメッセージを発生させます。

en: Don't write to files directly; use a temporary file and then use the ``atomic_move`` function from ``ansible.module_utils.basic`` to move the updated temporary file into place. This prevents data corruption and ensures that the correct context for the file is kept.
ja: ファイルに直接書き込まないようにします。一時ファイルを使用してから、``ansible.module_utils.basic`` の ``atomic_move`` 関数を使用して、更新された一時ファイルを所定の場所に移動させます。これにより、データの破損を防ぎ、ファイルの正しいコンテキストが保持されるようになります。

en: Avoid creating caches. Ansible is designed without a central server or authority, so you cannot guarantee it will not run with different permissions, options or locations. If you need a central authority, have it on top of Ansible (for example, using bastion/cm/ci server or tower); do not try to build it into modules.
ja: キャッシュを作成しないでください。Ansible は中央のサーバーや権限を持たないように設計されているため、さまざまなパーミッション、オプション、場所を指定して実行しないことを保証することはできません。中央の権限が必要な場合は、それを Ansible の上に置いてください (例: bastion/cm/ci サーバーまたは Tower を使用)。それをモジュールには組み込まないでください。

en: If you package your module(s) in an RPM, install the modules on the control machine in ``/usr/local/share/py38-ansible``. Packaging modules in RPMs is optional.
ja: RPM でモジュールをパッケージ化する場合は、コントロールマシンに ``/usr/local/share/py38-ansible`` のモジュールをインストールします。RPM でのモジュールのパッケージ化は任意です。

en: Functions and Methods
ja: 関数およびメソッド

en: Each function should be concise and should describe a meaningful amount of work.
ja: 各関数は簡潔にし、意味のある作業量を記述する必要があります。

en: "Don't repeat yourself" is generally a good philosophy.
ja: 「Don't repeat yourself (繰り返さないこと)」は、通常、適している哲学です。

en: Function names should use underscores: ``my_function_name``.
ja: 関数名はアンダースコアを使用する必要があります (``my_function_name``)。

en: The name of each function should describe what the function does.
ja: 各関数の名前には、関数の機能を記述する必要があります。

en: Each function should have a docstring.
ja: 各関数にはドキュメント文字列 (docstring) が必要です。

en: If your code is too nested, that's usually a sign the loop body could benefit from being a function. Parts of our existing code are not the best examples of this at times.
ja: コードの入れ子を多用しすぎている場合、それは通常、ループ本体が関数であることから利益が得られる可能性のある兆候です。既存のコードの一部は、時としてこのような例としては最適ではありません。

en: Python tips
ja: Python のヒント

en: Include a ``main`` function that wraps the normal execution.
ja: 通常の実行をラップする ``main`` 関数を含めます。

en: Call your ``main`` function from a conditional so you can import it into unit tests - for example:
ja: 条件から ``main`` 機能を呼び出して、ユニットテストにインポートします。以下に例を示します。

en: Importing and using shared code
ja: 共有コードのインポートおよび使用

en: Use shared code whenever possible - don't reinvent the wheel. Ansible offers the ``AnsibleModule`` common Python code, plus :ref:`utilities <developing_module_utilities>` for many common use cases and patterns. You can also create documentation fragments for docs that apply to multiple modules.
ja: 可能な限り共有コードを使用する - wheel を再実装しないでください。Ansible は ``AnsibleModule`` の一般的な Python コードと、多くの一般的なユースケースおよびパターンに使用する :ref:`ユーティリティー <developing_module_utilities>` を提供します。また、複数のモジュールに適用されるドキュメントフラグメントを作成することもできます。

en: Import ``ansible.module_utils`` code in the same place as you import other libraries.
ja: 他のライブラリーをインポートする場所と同じ場所に ``ansible.module_utils`` コードをインポートします。

en: Do NOT use wildcards (*) for importing other python modules; instead, list the function(s) you are importing (for example, ``from some.other_python_module.basic import otherFunction``).
ja: 他の python モジュールのインポートにはワイルドカード (*) を使用しないでください。代わりに、インポートする関数を一覧表示してください (例: ``from some.other_python_module.basic import otherFunction``。

en: Import custom packages in ``try``/``except``, capture any import errors, and handle them with ``fail_json()`` in ``main()``. For example:
ja: ``try``/``except`` でカスタムパッケージをインポートし、インポートエラーを捕捉し、``main()`` の ``fail_json()`` で処理します。以下は例となります。

en: Then in ``main()``, just after the argspec, do
ja: 次に ``main()`` で、argspec の直後に以下を実行します。

en: And document the dependency in the ``requirements`` section of your module's :ref:`documentation_block`.
ja: また、依存関係をモジュールの :ref:`documentation_block` の ``requirements`` セクションで記述します。

en: Handling module failures
ja: モジュール障害の処理

en: When your module fails, help users understand what went wrong. If you are using the ``AnsibleModule`` common Python code, the ``failed`` element will be included for you automatically when you call ``fail_json``. For polite module failure behavior:
ja: モジュールが失敗すると、ユーザーは問題を理解するのに役立ちます。一般的な Python コード ``AnsibleModule`` を使用している場合、``fail_json`` の呼び出し時に自動的に ``failed`` 要素が含まれます。polite モジュールの失敗動作には、以下を行います。

en: Include a key of ``failed`` along with a string explanation in ``msg``. If you don't do this, Ansible will use standard return codes: 0=success and non-zero=failure.
ja: ``msg`` の文字列の説明と共に ``failed`` のキーが含まれるようにします。これを行わないと、Ansible は標準の戻りコード 0=success および non-zero=failure を使用します。

en: Don't raise a traceback (stacktrace). Ansible can deal with stacktraces and automatically converts anything unparseable into a failed result, but raising a stacktrace on module failure is not user-friendly.
ja: トレースバック (スタックトレース) は発生させません。Ansible はスタックトレースを扱うことができ、解析できないものは自動的に失敗した結果に変換しますが、モジュールの失敗時にスタックトレースを発生させるのはユーザーフレンドリーではありません。

en: Do not use ``sys.exit()``. Use ``fail_json()`` from the module object.
ja: ``sys.exit()`` は使用しないでください。モジュールオブジェクトの ``fail_json()`` を使用してください。

en: Handling exceptions (bugs) gracefully
ja: 例外 (バグ) を正常に処理

en: Validate upfront--fail fast and return useful and clear error messages.
ja: 前もって検証します。早めに失敗し、有用で明確なエラーメッセージを返します。

en: Use defensive programming--use a simple design for your module, handle errors gracefully, and avoid direct stacktraces.
ja: 防御的なプログラミングを使用します。モジュールにはシンプルなデザインを使用し、エラーを適切に処理し、直接のスタックトレースを回避します。

en: Fail predictably--if we must fail, do it in a way that is the most expected. Either mimic the underlying tool or the general way the system works.
ja: 予測可能な方法で失敗させます。失敗がどうしても避けられない場合は、最も期待される方法で失敗します。基礎となるツール、またはシステムの一般的な動作方法を模倣します。

en: Give out a useful message on what you were doing and add exception messages to that.
ja: 実行内容に関する有用なメッセージを表示して、それに例外メッセージを追加します。

en: Avoid catchall exceptions, they are not very useful unless the underlying API gives very good error messages pertaining the attempted action.
ja: キャッチオール例外は使用しないでください。基になる API が試行されたアクションに関して非常に優れたエラーメッセージがない限り、これらの例外はほとんど役に立ちません。

en: Creating correct and informative module output
ja: 正確で有益なモジュール出力を作成

en: Modules must output valid JSON only. Follow these guidelines for creating correct, useful module output:
ja: モジュールは有効な JSON のみを出力しなければなりません。正確で有用なモジュール出力を作成するには、以下のガイドラインに従ってください。

en: Make your top-level return type a hash (dictionary).
ja: 最上位レベルの戻り値の型をハッシュ (ディレクトリー) にします。

en: Nest complex return values within the top-level hash.
ja: 複雑な戻り値をトップレベルのハッシュ内に入れ子にします。

en: Incorporate any lists or simple scalar values within the top-level return hash.
ja: 最上位レベルの戻り値ハッシュ内にリストや単純なスカラー値を組み込みます。

en: Do not send module output to standard error, because the system will merge standard out with standard error and prevent the JSON from parsing.
ja: モジュールの出力を標準エラーに送らないでください。システムが標準エラーと標準出力をマージし、JSON の解析を妨げるためです。

en: Capture standard error and return it as a variable in the JSON on standard out. This is how the command module is implemented.
ja: 標準エラーを取得し、標準出力の JSON で変数として返します。これは、コマンドモジュールの実装方法です。

en: Never do ``print("some status message")`` in a module, because it will not produce valid JSON output.
ja: 有効な JSON 出力が生成されないため、モジュールで ``print("some status message")`` を実行しないでください。

en: Always return useful data, even when there is no change.
ja: 変更がない場合でも、有用なデータを常に返します。

en: Be consistent about returns (some modules are too random), unless it is detrimental to the state/action.
ja: 状態/アクションに有害でない限り、戻り値は一貫したものにしてください (モジュールによっては非常に乱雑なものもあります)。

en: Make returns reusable--most of the time you don't want to read it, but you do want to process it and re-purpose it.
ja: 戻り値は再利用可能なものにします。ほとんどの場合は読むことはありませんが、処理して再利用できるものにします。

en: Return diff if in diff mode. This is not required for all modules, as it won't make sense for certain ones, but please include it when applicable.
ja: diff モードの場合は diff を返します。これは、特定のモジュールでは意味をなさないため、すべてのモジュールに必要なわけではありませんが、該当する場合には使用してください。

en: Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, and so on) are serializable.
ja: Python の標準の `JSON エンコーダーおよびデコーダー <https://docs.python.org/3/library/json.html>` ライブラリーで、戻り値を JSON としてシリアライズできるようにします。基本的な python タイプ (文字列、int、ディクショナリー、リストなど) はシリアライズ可能です。

en: Do not return an object using exit_json(). Instead, convert the fields you need from the object into the fields of a dictionary and return the dictionary.
ja: exit_json() を使用してオブジェクトを返さないでください。代わりに、オブジェクトの必要なフィールドをディクショナリーのフィールドに変換して返します。

en: Results from many hosts will be aggregated at once, so your module should return only relevant output. Returning the entire contents of a log file is generally bad form.
ja: 多数のホストからの結果が一度に集約されるため、モジュールは関連する出力だけを返すべきです。ログファイルの内容全体を返すのは、一般的には悪い形式です。

en: If a module returns stderr or otherwise fails to produce valid JSON, the actual output will still be shown in Ansible, but the command will not succeed.
ja: モジュールが stderr を返すか、有効な JSON の生成に失敗した場合でも、実際の出力は Ansible に表示されますが、コマンドは成功しません。

en: Following Ansible conventions
ja: Ansible の規則に準拠

en: Ansible conventions offer a predictable user interface across all modules, playbooks, and roles. To follow Ansible conventions in your module development:
ja: Ansible の規則は、すべてのモジュール、Playbook、ロールに渡って予測可能なユーザーインターフェースを提供します。モジュール開発において Ansible の規則に従うには、以下を行います。

en: Use consistent names across modules (yes, we have many legacy deviations - don't make the problem worse!).
ja: モジュール間で一貫性のある名前を使用します (レガシーとの相違が多数あるため、問題を悪化させないようにしましょう)。

en: Use consistent options (arguments) within your module(s).
ja: モジュール内で一貫したオプション (引数) を使用します。

en: Do not use 'message' or 'syslog_facility' as an option name, because this is used internally by Ansible.
ja: これは Ansible によって内部で使用されるため、オプション名には「message」または「syslog_facility」を使用しないでください。

en: Normalize options with other modules - if Ansible and the API your module connects to use different names for the same option, add aliases to your options so the user can choose which names to use in tasks and playbooks.
ja: 他のモジュールでオプションを正規化します。Ansible と、モジュールが接続する API が同じオプションに異なる名前を使用している場合は、オプションにエイリアスを追加して、ユーザーがタスクおよび Playbook で使用する名前を選択できるようにします。

en: Return facts from ``*_facts`` modules in the ``ansible_facts`` field of the :ref:`result dictionary<common_return_values>` so other modules can access them.
ja: 他のモジュールがそれらにアクセスできるように、:ref:`結果ディクショナリー<common_return_values>` の ``ansible_facts`` フィールドの ``*_facts`` モジュールからファクトを返します。

en: Implement ``check_mode`` in all ``*_info`` and ``*_facts`` modules. Playbooks which conditionalize based on fact information will only conditionalize correctly in ``check_mode`` if the facts are returned in ``check_mode``. Usually you can add ``supports_check_mode=True`` when instantiating ``AnsibleModule``.
ja: すべての ``*_info`` および ``*_facts`` モジュールに ``check_mode`` を実装します。ファクト情報をもとに条件付けされる Playbook は、ファクトが ``check_mode`` で返される場合にのみ ``check_mode`` で条件化されます。 通常は、``AnsibleModule`` をインスタンス化する時に ``supports_check_mode=True`` を追加することができます。

en: Use module-specific environment variables. For example, if you use the helpers in ``module_utils.api`` for basic authentication with ``module_utils.urls.fetch_url()`` and you fall back on environment variables for default values, use a module-specific environment variable like :code:`API_<MODULENAME>_USERNAME` to avoid conflicts between modules.
ja: モジュール固有の環境変数を使用します。たとえば、``module_utils.urls.fetch_url()`` での基本的な認証に ``module_utils.api`` のヘルパーを使用し、デフォルト値を環境変数に依存している場合は、モジュール間の競合を回避するために :code:`API_<MODULENAME>_USERNAME` のようなモジュール固有の環境変数を使用します。

en: Keep module options simple and focused - if you're loading a lot of choices/states on an existing option, consider adding a new, simple option instead.
ja: モジュールのオプションはシンプルで焦点を絞ったものにします。既存のオプションに多くの選択肢や状態を読み込んでいる場合は、代わりに新しいシンプルなオプションを追加することを検討してください。

en: Keep options small when possible. Passing a large data structure to an option might save us a few tasks, but it adds a complex requirement that we cannot easily validate before passing on to the module.
ja: 可能な場合はオプションのサイズを小さくします。大きなデータ構造をオプションに渡すと、いくつかの作業が省けるかもしれませんが、モジュールに渡す前に簡単に検証できない複雑な要件が追加されてしまいます。

en: If you want to pass complex data to an option, write an expert module that allows this, along with several smaller modules that provide a more 'atomic' operation against the underlying APIs and services. Complex operations require complex data. Let the user choose whether to reflect that complexity in tasks and plays or in  vars files.
ja: 複雑なデータをオプションに渡したいのであれば、それを可能にするエキスパートモジュールと、基礎となる API やサービスに対してより「アトミックな」操作を提供するいくつかの小さなモジュールを作成します。複雑な操作には複雑なデータが必要です。その複雑さをタスクやプレイに反映させるか、vars ファイルに反映させるかをユーザが選択できるようにします。

en: Implement declarative operations (not CRUD) so the user can ignore existing state and focus on final state. For example, use ``started/stopped``, ``present/absent``.
ja: ユーザーが既存の状態を無視して最終的な状態に集中できるように、(CRUDではなく) 宣言的な操作を実装します。たとえば、``started/stopped``、``present/absent`` を使用します。

en: Strive for a consistent final state (aka idempotency). If running your module twice in a row against the same system would result in two different states, see if you can redesign or rewrite to achieve consistent final state. If you can't, document the behavior and the reasons for it.
ja: 最終状態が一貫したもの (別名、冪等性) になるようにします。同じシステムに対してモジュールを連続して 2 回実行すると 2 つの異なる状態になってしまう場合は、最終的な状態が一貫しているかどうかを再設計または書き換えてみてください。できない場合は、動作とその理由を記載してください。

en: Provide consistent return values within the standard Ansible return structure, even if NA/None are used for keys normally returned under other options.
ja: 通常は他のオプションで返されるキーに NA/None が使用されている場合でも、標準の Ansible の戻り値構造内で一貫性のある戻り値を提供します。

en: Follow additional guidelines that apply to families of modules if applicable. For example, AWS modules should follow the  :ref:`Amazon development checklist <AWS_module_development>`.
ja: 該当する場合は、モジュールのファミリーに適用される追加のガイドラインに従います。たとえば、AWS モジュールは :ref:`Amazon development checklist <AWS_module_development>` に従う必要があります。

en: Module Security
ja: モジュールのセキュリティー

en: Avoid passing user input from the shell.
ja: シェルからユーザー入力を渡さないようにします。

en: Always check return codes.
ja: 常に戻りコードを確認してください。

en: You must always use ``module.run_command``, not ``subprocess`` or ``Popen`` or ``os.system``.
ja: ``subprocess``、``Popen``、または ``os.system`` ではなく、常に ``module.run_command`` を使用する必要があります。

en: Avoid using the shell unless absolutely necessary.
ja: 絶対に必要な場合を除き、シェルは使用しないでください。

en: If you must use the shell, you must pass ``use_unsafe_shell=True`` to ``module.run_command``.
ja: シェルを使用する必要がある場合は、``use_unsafe_shell=True`` を ``module.run_command`` に渡す必要があります。

en: If any variables in your module can come from user input with ``use_unsafe_shell=True``, you must wrap them with ``pipes.quote(x)``.
ja: モジュールの変数が ``use_unsafe_shell=True`` を使用してユーザー入力から送られる場合は、``pipes.quote(x)`` でラップする必要があります。

en: When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do not use ``urllib2``, which does not natively verify TLS certificates and so is insecure for https.
ja: URL を取得する際には、``ansible.module_utils.urls`` から ``fetch_url`` または ``open_url`` を使用してください。``urllib2`` を使用しないでください。TLS 証明書をネイティブで検証しないため、https では安全ではありません。

en: Sensitive values marked with ``no_log=True`` will automatically have that value stripped from module return values. If your module could return these sensitive values as part of a dictionary key name, you should call the ``ansible.module_utils.basic.sanitize_keys()`` function to strip the values from the keys. See the ``uri`` module for an example.
ja: ``no_log=True`` のマークが付いた機密値は自動的に、モジュールの戻り値から取り除かれます。モジュールがこれらの機密値をディクショナリーキー名の一部として返すことができる場合は、``ansible.module_utils.basic.sanitize_keys()`` 関数を呼び出してキーから値を取り除く必要があります。たとえば、``uri`` モジュールを参照してください。

en: Contributing your module to an existing Ansible collection
ja: 既存の Ansible コレクションへのモジュールの貢献

en: If you want to contribute a module to an existing collection, you must meet the community's objective and subjective requirements. Please read the details below, and also review our :ref:`tips for module development <developing_modules_best_practices>`.
ja: 既存のコレクションにモジュールを提供する場合は、コミュニティーの目的の要件と主体的な要件を満たす必要があります。以下の詳細を読み、「:ref:`モジュール開発のヒント <developing_modules_best_practices>`」も確認してください。

en: Modules accepted into certain collections are included in every Ansible release on PyPI. However, contributing to one of these collections is not the only way to distribute a module - you can :ref:`create your own collection <developing_collections>`, embed modules in roles on Galaxy or simply share copies of your module code for :ref:`local use <developing_locally>`.
ja: 特定のコレクションで許可されるモジュールは、PyPI のすべての Ansible リリースに含まれます。ただし、これらのコレクションのいずれかに貢献することが、モジュールを配布する唯一の方法ではありません。:ref:`独自のコレクションの作成 <developing_collections>` は、Galaxy のロールにモジュールコードのコピーを埋め込んだり、:ref:`ローカルでの使用 <developing_locally>` 用にモジュールコードのコピーを共有することもできます。

en: Contributing modules: objective requirements
ja: モジュールの貢献: 目的要件

en: To contribute a module to most Ansible collections, you must:
ja: モジュールをほとんどの Ansible コレクションに提供するには、以下を行う必要があります。

en: write your module in either Python or Powershell for Windows
ja: Windows 用の Python または Powershell のいずれかでモジュールを書き込みます。

en: use the ``AnsibleModule`` common code
ja: ``AnsibleModule`` 共通コードを使用します。

en: support Python 2.6 and Python 3.5 - if your module cannot support Python 2.6, explain the required minimum Python version and rationale in the requirements section in ``DOCUMENTATION``
ja: Python 2.6 および Python 3.5 をサポートします。モジュールが Python 2.6 をサポートできない場合は、``DOCUMENTATION`` の要件セクションで、最低限必要な Python バージョンと根拠を説明します。

en: use proper :ref:`Python 3 syntax <developing_python_3>`
ja: 適切な :ref:`Python 3 構文 <developing_python_3>` を使用します。

en: follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ Python style conventions - see :ref:`testing_pep8` for more information
ja: `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ Python スタイルの規則に従います。詳細は「:ref:`testing_pep8`」を参照してください。

en: license your module under the GPL license (GPLv3 or later)
ja: GPL ライセンス (GPLv3 以降) でモジュールにライセンスを付与します。

en: understand the :ref:`license agreement <contributor_license_agreement>`, which applies to all contributions
ja: すべての貢献に適用される :ref:`ライセンス合意 <contributor_license_agreement>` を理解します。

en: conform to Ansible's :ref:`formatting and documentation <developing_modules_documenting>` standards
ja: Ansible の :ref:`formatting and documentation <developing_modules_documenting>` 標準規格に準拠しています。

en: include comprehensive :ref:`tests <developing_testing>` for your module
ja: モジュールに包括的な :ref:`tests <developing_testing>` を含めます。

en: minimize module dependencies
ja: モジュール依存関係を最小限に抑えます。

en: support :ref:`check_mode <check_mode_dry>` if possible
ja: 可能な場合は :ref:`check_mode <check_mode_dry>` をサポートします。

en: ensure your code is readable
ja: コードが読み取り可能であることを確認します。

en: if a module is named ``<something>_facts``, it should be because its main purpose is returning ``ansible_facts``. Do not name modules that do not do this with ``_facts``. Only use ``ansible_facts`` for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed.
ja: モジュールの名前が ``<something>_facts`` なのは、``ansible_facts`` を返すことが主な目的だからです。これは、``_facts`` でこれを行わないモジュールに名前を付けないでください。ネットワークインターフェースやその設定や、オペレーティングシステムやインストールされているプログラムなど、ホストマシンに固有の情報には ``ansible_facts`` のみを使用してください。

en: Modules that query/return general information (and not ``ansible_facts``) should be named ``_info``. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine.
ja: 一般情報をクエリー/返送するモジュールは (``ansible_facts`` ではなく) ``_info`` という名前にする必要があります。一般情報とは、ホスト固有ではない情報、たとえば、オンライン/クラウドサービスに関する情報 (同じホストから同じオンラインサービスの異なるアカウントにアクセスできます)、または、マシンからアクセス可能な仮想マシンおよびコンテナーに関する情報になります。

en: Additional requirements may apply for certain collections. Review the individual collection repositories for more information.
ja: 追加の要件は、特定のコレクションに適用される可能性があります。詳細は、個別のコレクションリポジトリーを参照してください。

en: Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, reach out via ``#ansible-devel``, Ansible's IRC chat channel on `irc.libera.chat <http://libera.chat>`_ or the `Ansible development mailing list <https://groups.google.com/group/ansible-devel>`_.
ja: PR/提案を送信する前に、お使いのモジュールがこれらの要件を満たしていることを確認してください。ご不明な点がございましたら、``#ansible-devel``、`irc.libera.chat <http://libera.chat>`_ における Ansible の IRC チャットチャンネル、または `Ansible 開発メーリングリスト <https://groups.google.com/group/ansible-devel>`_ までお問い合わせください。

en: Contributing to Ansible: subjective requirements
ja: Ansible への貢献: 主観的な要件

en: If your module meets these objective requirements, collection maintainers will review your code to see if they think it's clear, concise, secure, and maintainable. They will consider whether your module provides a good user experience, helpful error messages, reasonable defaults, and more. This process is subjective, with no exact standards for acceptance. For the best chance of getting your module accepted, follow our :ref:`tips for module development <developing_modules_best_practices>`.
ja: モジュールがこれらの目的の要件を満たす場合は、コレクションのメンテナーが、明確、簡潔、安全であり、維持が可能であると考えるコードを確認します。モジュールが優れたユーザーエクスペリエンスを提供し、有用なエラーメッセージ、有益なデフォルトなどを提供するかどうかを考慮します。このプロセスは主観的で、正確な標準はありません。モジュールが受け入れられる可能性を最大限に高めるには、「:ref:`モジュール開発のヒント <developing_modules_best_practices>`」に従ってください。

en: Other checklists
ja: その他のチェックリスト

en: :ref:`Tips for module development <developing_modules_best_practices>`.
ja: :ref:`モジュール開発のヒント <developing_modules_best_practices>`

en: :ref:`Amazon development checklist <AWS_module_development>`.
ja: :ref:`Amazon 開発チェックリスト <AWS_module_development>`

en: :ref:`Windows development checklist <developing_modules_general_windows>`.
ja: :ref:`Windows 開発チェックリスト <developing_modules_general_windows>`

en: Module format and documentation
ja: モジュールの形式およびドキュメント

en: If you want to contribute your module to most Ansible collections, you must write your module in Python and follow the standard format described below. (Unless you're writing a Windows module, in which case the :ref:`Windows guidelines <developing_modules_general_windows>` apply.) In addition to following this format, you should review our :ref:`submission checklist <developing_modules_checklist>`, :ref:`programming tips <developing_modules_best_practices>`, and :ref:`strategy for maintaining Python 2 and Python 3 compatibility <developing_python_3>`, as well as information about :ref:`testing <developing_testing>` before you open a pull request.
ja: モジュールをほとんどの Ansible コレクションに貢献する場合は、Python でモジュールを作成して、その標準形式に従う必要があります。(Windows モジュールを作成したことがない場合。この場合は、:ref:`Windows ガイドライン <developing_modules_general_windows>` が適用されます)。この形式に従うことに加え、プル要求を作成する前に、:ref:`提出のチェックリスト <developing_modules_checklist>`、:ref:`プログラムのヒント <developing_modules_best_practices>`、:ref:`Python 2 および Python 3 互換性の維持のストラテジー <developing_python_3>` と、:ref:`テスト <developing_testing>` に関する情報をお読みください。

en: Every Ansible module written in Python must begin with seven standard sections in a particular order, followed by the code. The sections in order are:
ja: Python で書かれたすべての Ansible モジュールは、特定の順序で 7 つの標準セクションから始まり、その後にコードが続きます。セクションの順番は以下のとおりです。

en: Why don't the imports go first?
ja: 最初にインポートが行われないのはなぜですか。

en: Keen Python programmers may notice that contrary to PEP 8's advice we don't put ``imports`` at the top of the file. This is because the ``DOCUMENTATION`` through ``RETURN`` sections are not used by the module code itself; they are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP 8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP 8 is about). Documentation strings in a module are much more similar to module level docstrings, than code, and are never utilized by the module itself. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.
ja: 熱心な Python プログラマーは、PEP 8 のアドバイスに反して、ファイルの冒頭に ``imports`` を置いていないことに気づくかもしれません。これは、``RETURN`` までの ``DOCUMENTATION`` セクションはモジュールコード自体で使用されておらず、基本的にファイルに追加のドキュメント文字列を使用するためです。インポートは、PEP 8 と同じ理由でこれらの特別な変数の後に置かれ、紹介のコメントとドキュメント文字列の後にインポートを追加します。これにより、コードの活動的な部分が一緒になり、純粋に情報を提供する部分が分離されます。E402 を除外する意思決定は (PEP 8 の目的である) 可読性に基づいています。モジュール内のドキュメント文字列は、コードよりも、モジュールレベルのドキュメント文字列によく似ており、モジュール自体が利用することはありません。インポートを、このドキュメントの下の、よりコードに近いところに置くことで、関連するすべてのコードを統合してグループ化し、可読性、デバッグ、理解を向上させます。

en: **Copy old modules with care!**
ja: **古いモジュールは注意してコピーしてください。**

en: Some older Ansible modules have ``imports`` at the bottom of the file, ``Copyright`` notices with the full GPL prefix, and/or ``DOCUMENTATION`` fields in the wrong order. These are legacy files that need updating - do not copy them into new modules. Over time we are updating and correcting older modules. Please follow the guidelines on this page!
ja: 一部の古い Ansible モジュールでは、ファイルの下部に ``imports`` があるため、``Copyright`` は完全な GPL プレフィックス、または ``DOCUMENTATION`` フィールドを間違った順序で持つことに注意してください。これらは更新が必要なレガシーファイルです。新しいモジュールにコピーしないでください。時間の経過とともに、古いモジュールを更新および修正しています。このページにはガイドラインに従うようにしてください。

en: Python shebang & UTF-8 coding
ja: Python シバンおよび UTF-8 コーディング

en: Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``ansible_python_interpreter`` to work. Follow the shebang immediately with ``# -*- coding: utf-8 -*-`` to clarify that the file is UTF-8 encoded.
ja: ``#!/usr/bin/python`` で Ansible モジュールを開始します (この「シバン」では ``ansible_python_interpreter`` が機能します)。ファイルが UTF-8 でエンコードされていることを明確にするために、シバンの直後に ``# -*- coding: utf-8 -*-`` を使用します。

en: Copyright and license
ja: 著作権およびライセンス

en: After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
ja: シバンおよび UTF-8 コーディングの後に、元の著作権所有者およびライセンス宣言を含む `著作権行 <https://www.gnu.org/licenses/gpl-howto.en.html>`_ を追加します。ライセンス宣言は、完全な GPL プレフィックスではなく、1 行のみにする必要があります。

en: Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary. Please do not edit the existing copyright year. This simplifies project administration and is unlikely to cause any interesting legal issues. When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:
ja: モジュールへの主要な追加 (たとえば、書き換え) は、により、著作権行が追加される場合があります。法的な審査にはソース管理履歴が含まれるため、網羅的な著作権ヘッダーは必要ありません。既存の著作権年は編集しないでください。これは、プロジェクトの管理を単純化するものであり、興味深い法的問題を引き起こす可能性はほとんどありません。重要な機能や書き換えのために 2 つ目の著作権行を追加する場合は、古い行の上に新しい行を追加します。

en: ANSIBLE_METADATA block
ja: ANSIBLE_METADATA ブロック

en: Since we moved to collections we have deprecated the METADATA functionality, it is no longer required for modules, but it will not break anything if present.
ja: コレクションに移行しても METADATA 機能は非推奨になり、モジュールには必要なくなりましたが、存在しても何も破損しません。

en: DOCUMENTATION block
ja: DOCUMENTATION ブロック

en: After the shebang, the UTF-8 coding, the copyright line, and the license section comes the ``DOCUMENTATION`` block. Ansible's online module documentation is generated from the ``DOCUMENTATION`` blocks in each module's source code. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file. You can start by copying our `example documentation string <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ into your module file and modifying it. If you run into syntax issues in your YAML, you can validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
ja: shebang、UTF-8 コーディング、著作権行、ライセンスセクションの後には、``DOCUMENTATION`` ブロックがあります。Ansible のオンラインモジュールドキュメントは、各モジュールのソースコード内の ``DOCUMENTATION`` ブロックから生成されます。``DOCUMENTATION`` ブロックは有効な YAML でなければなりません。Python ファイルに含める前に、``DOCUMENTATION`` の文字列を :ref:`YAML 構文の強調表示を使用したエディター <other_tools_and_programs>` に書き始めた方が簡単だと思うかもしれません。提供している `サンプルのドキュメントの文字列 <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_ を自身のモジュールファイルにコピーして、それを修正することから始めることができます。YAML の構文に問題がある場合は、`YAML Lint <http://www.yamllint.com/>`_ の Web サイトで検証することができます。

en: Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts.
ja: モジュールのドキュメントでは、各モジュールとオプションの動作について簡単かつ正確に定義し、基礎となるシステムで他のモジュールとどのように連携するかを説明します。ドキュメントは、専門家と非専門家の両方が読むことができるように、幅広い読者に向けて作成する必要があります。

en: Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
ja: 説明は常に大文字で始め、完全に終了する必要があります。一貫性は常に役立ちます。

en: Verify that arguments in doc and module spec dict are identical.
ja: ドキュメントの引数と、モジュール仕様のディクショナリーが同じであることを確認します。

en: For password / secret arguments ``no_log=True`` should be set.
ja: パスワード/シークレット引数 ``no_log=True`` を設定する必要があります。

en: For arguments that seem to contain sensitive information but **do not** contain secrets, such as "password_length", set ``no_log=False`` to disable the warning message.
ja: 機密情報が含まれているように見えても「password_length」などのシークレットが **含まれていない** ように表示される引数には、``no_log=False`` を設定して警告メッセージを無効にします。

en: If an option is only sometimes required, describe the conditions. For example, "Required when I(state=present)."
ja: オプションのみが必要な場合は、条件を記述してください。たとえば、「Required when I(state=present)」です。

en: If your module allows ``check_mode``, reflect this fact in the documentation.
ja: モジュールで ``check_mode`` が許可されている場合は、これをドキュメントに反映させます。

en: To create clear, concise, consistent, and useful documentation, follow the :ref:`style guide <style_guide>`.
ja: 明確かつ簡潔で一貫性があり、便利なドキュメントは :ref:`スタイルガイド <style_guide>` に従います。

en: Each documentation field is described below. Before committing your module documentation, please test it at the command line and as HTML:
ja: 各ドキュメントフィールドの説明は次のとおりです。モジュールのドキュメントをコミットする前に、コマンドラインおよび HTML でテストしてください。

en: As long as your module file is :ref:`available locally <local_modules>`, you can use ``ansible-doc -t module my_module_name`` to view your module documentation at the command line. Any parsing errors will be obvious - you can view details by adding ``-vvv`` to the command.
ja: モジュールファイルが :ref:`ローカルで利用可能 <local_modules>` な場合に限り、``ansible-doc -t module my_module_name`` を使用して、コマンドラインでモジュールのドキュメントを表示します。構文解析エラーは明確になります。コマンドに ``-vvv`` を追加すると、詳細を表示できます。

en: You should also :ref:`test the HTML output <testing_module_documentation>` of your module documentation.
ja: モジュールのドキュメントにおける :ref:`HTML 出力のテスト <testing_module_documentation>` も必要です。

en: Documentation fields
ja: ドキュメントフィールド

en: All fields in the ``DOCUMENTATION`` block are lower-case. All fields are required unless specified otherwise:
ja: ``DOCUMENTATION`` ブロックのフィールドはすべて小文字になります。特に指定がない場合は、すべてのフィールドが必要になります。

en: The name of the module.
ja: モジュールの名前。

en: Must be the same as the filename, without the ``.py`` extension.
ja: ファイル名と同じ (``.py`` 拡張子なし) である必要があります。

en: A short description which is displayed on the :ref:`list_of_collections` page and ``ansible-doc -l``.
ja: :ref:`list_of_collections` ページと ``ansible-doc -l`` に表示される簡単な説明です。

en: The ``short_description`` is displayed by ``ansible-doc -l`` without any category grouping, so it needs enough detail to explain the module's purpose without the context of the directory structure in which it lives.
ja: ``short_description`` は、カテゴリーをグループ化せずに、``ansible-doc -l`` によって表示されます。そのため、モジュールが存在するディレクトリー構造のコンテキストなしでモジュールの目的を説明するのに十分な詳細が必要です。

en: Unlike ``description:``, ``short_description`` should not have a trailing period/full stop.
ja: ``description:`` とは異なり、``short_description`` のピリオド (文末) は設定しないでください。

en: A detailed description (generally two or more sentences).
ja: 詳細な説明 (通常は 2 文以上)。

en: Must be written in full sentences, in other words, with capital letters and periods/full stops.
ja: 文章の形、つまり冒頭の大文字やピリオド (文末) などを使用して記述する必要があります。

en: Shouldn't mention the module name.
ja: モジュール名について言及すべきではありません。

en: Make use of multiple entries rather than using one long paragraph.
ja: 1 つの長い段落にせず、複数の文章に分けます。

en: Don't quote complete values unless it is required by YAML.
ja: YAML で必要な場合を除き、完全な値を引用符で囲まないでください。

en: The version of Ansible when the module was added.
ja: モジュールが追加された Ansible のバージョン。

en: This is a string, and not a float, for example, ``version_added: '2.1'``.
ja: これは浮動小数点ではなく文字列です (例: ``version_added: '2.1'``)。

en: In collections, this must be the collection version the module was added to, not the Ansible version. For example, ``version_added: 1.0.0``.
ja: コレクションでは、これは Ansible バージョンではなく、モジュールが追加されたコレクションバージョンでなければなりません (例: ``version_added: 1.0.0``)。

en: Name of the module author in the form ``First Last (@GitHubID)``.
ja: ``First Last (@GitHubID)`` 形式のモジュール作成者の名前。

en: Use a multi-line list if there is more than one author.
ja: 作成者が複数になる場合は、複数行のリストを使用します。

en: Don't use quotes as it should not be required by YAML.
ja: YAML では必要ないため、引用符は使用しないでください。

en: Marks modules that will be removed in future releases. See also :ref:`module_lifecycle`.
ja: 将来のリリースで削除されるモジュールにマークを付けします。「:ref:`module_lifecycle`」も併せて参照してください。

en: Options are often called `parameters` or `arguments`. Because the documentation field is called `options`, we will use that term.
ja: オプションは、多くの場合、`パラメーター` または `引数` と呼ばれます。ドキュメントフィールドは `オプション` を呼ばれるため、ここではその用語を使用します。

en: If the module has no options (for example, it's a ``_facts`` module), all you need is one line: ``options: {}``.
ja: モジュールにオプションがない (例: ``_facts`` モジュール) 場合、必要なのは 1 行 (``options: {}``) だけです。

en: If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module option, include:
ja: モジュールにオプションがある (つまり引数を受け入れる) 場合、各オプションは詳細に文書化される必要があります。各モジュールオプションについて、以下を記載します。

en: Declarative operation (not CRUD), to focus on the final state, for example `online:`, rather than `is_online:`.
ja: (CRUD ではなく) 宣言操作は、「`is_online:`」ではなく、「`online:`」などの最終状態に焦点をあてます。

en: The name of the option should be consistent with the rest of the module, as well as other modules in the same category.
ja: オプションの名前は、そのモジュールの残りの部分、および同じカテゴリーの他のモジュールと一貫性を持たせる必要があります。

en: When in doubt, look for other modules to find option names that are used for the same purpose, we like to offer consistency to our users.
ja: 不明な場合は、他のモジュールを探して、同じ目的で使用されているオプション名を見つけてください。ユーザーに一貫性を提供できるようにしています。

en: Detailed explanation of what this option does. It should be written in full sentences.
ja: このオプションの機能の詳細な説明。これは、完全な文章で記述する必要があります。

en: The first entry is a description of the option itself; subsequent entries detail its use, dependencies, or format of possible values.
ja: 最初のエントリーは、オプションそのものの説明です。後続のエントリーは、その使用、依存関係、または使用できる値の形式の詳細を説明します。

en: Should not list the possible values (that's what ``choices:`` is for, though it should explain what the values do if they aren't obvious).
ja: 可能な値を列挙しないでください (``choices:`` はそのためにあります。値が明らかでない場合は、その値が何を示すのかを説明してください)。

en: Mutually exclusive options must be documented as the final sentence on each of the options.
ja: 相互に排他的なオプションは、各オプションの最後の文で文書化する必要があります。

en: Only needed if ``true``.
ja: ``true`` の場合にのみ必要です。

en: If missing, we assume the option is not required.
ja: 見つからない場合は、オプションが不要であると仮定します。

en: If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing).
ja: ``required`` が false もしくは指定されていない場合は、``default`` を指定できます (見つからない場合は「null」と見なされます)。

en: Ensure that the default value in the docs matches the default value in the code.
ja: ドキュメントのデフォルト値が、コードのデフォルト値と一致していることを確認してください。

en: The default field must not be listed as part of the description, unless it requires additional information or conditions.
ja: 追加の情報や条件が必要な場合を除き、デフォルトのフィールドは、説明の一部として記載しないでください。

en: If the option is a boolean value, you can use any of the boolean values recognized by Ansible: (such as true/false or yes/no).  Choose the one that reads better in the context of the option.
ja: オプションがブール値の場合は、Ansible が認識する任意のブール値 (true/false、yes/no など) を使用できます。オプションのコンテキストで読み取りが適切であればこれを選択します。

en: List of option values.
ja: オプション値のリスト。

en: Should be absent if empty.
ja: 空欄の場合は指定なしになります。

en: Specifies the data type that option accepts, must match the ``argspec``.
ja: オプションで使用できるデータ型を指定します。``argspec`` と一致させる必要があります。

en: If an argument is ``type='bool'``, this field should be set to ``type: bool`` and no ``choices`` should be specified.
ja: 引数が ``type='bool'`` の場合、このフィールドは ``type: bool`` に設定されます。``choices`` は指定しないでください。

en: If an argument is ``type='list'``, ``elements`` should be specified.
ja: 引数が ``type='list'`` の場合は、``elements`` を指定する必要があります。

en: Specifies the data type for list elements in case ``type='list'``.
ja: ``type='list'`` の場合に、リスト要素のデータ型を指定します。

en: List of optional name aliases.
ja: 任意の名前エイリアスのリスト。

en: Generally not needed.
ja: 一般的には必要ありません。

en: Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
ja: このオプションが Ansible の初回リリース後に拡張されている場合にのみ必要です。つまり、これは最上位レベルの `version_added` フィールドよりも大きくなります。

en: This is a string, and not a float, for example, ``version_added: '2.3'``.
ja: これは浮動小数点ではなく文字列です (例: ``version_added: '2.3'``)。

en: In collections, this must be the collection version the option was added to, not the Ansible version. For example, ``version_added: 1.0.0``.
ja: コレクションでは、これは Ansible バージョンではなく、オプションが追加されたコレクションバージョンでなければなりません (例: ``version_added: 1.0.0``)。

en: If this option takes a dict or list of dicts, you can define the structure here.
ja: このオプションがディクショナリーまたはディクショナリーのリストを取る場合は、ここで構造を定義できます。

en: See :ref:`ansible_collections.azure.azcollection.azure_rm_securitygroup_module`, :ref:`ansible_collections.azure.azcollection.azure_rm_azurefirewall_module`, and :ref:`ansible_collections.openstack.cloud.baremetal_node_action_module` for examples.
ja: 例は、「:ref:`ansible_collections.azure.azcollection.azure_rm_securitygroup_module`」、「:ref:`ansible_collections.azure.azcollection.azure_rm_azurefirewall_module`」、および「:ref:`ansible_collections.openstack.cloud.baremetal_node_action_module`」を参照してください。

en: List of requirements (if applicable).
ja: 要件のリスト (該当する場合)。

en: Include minimum versions.
ja: 最小バージョンを指定します。

en: A list of references to other modules, documentation or Internet resources
ja: その他のモジュール、ドキュメント、またはインターネットリソースへの参照の一覧。

en: In Ansible 2.10 and later, references to modules must use  the FQCN or ``ansible.builtin`` for modules in ``ansible-core``.
ja: Ansible 2.10 以降では、モジュールへの参照が ``ansible-core`` のモジュールに FQCN または ``ansible.builtin`` を使用する必要があります。

en: A reference can be one of the following formats:
ja: 参照には、以下の形式のいずれかを使用できます。

en: Details of any important information that doesn't fit in one of the above sections.
ja: 上記のセクションのいずれかに該当しない重要な情報の詳細。

en: For example, whether ``check_mode`` is or is not supported.
ja: たとえば、``check_mode`` がサポートされるかどうかなどです。

en: Linking and other format macros within module documentation
ja: モジュールドキュメント内のリンクおよびその他の形式マクロ

en: You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:
ja: モジュールドキュメントから他のモジュールドキュメント、docs.ansible.com の他のリソース、一部の事前設定マクロでインターネット上の他のリソースにリンクできます。これらのマクロの正しい形式は次のとおりです。

en: ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
ja: ``L()`` 見出しへのリンク。たとえば、``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` となります。Ansible 2.10 以降、Ansible ドキュメントとコレクションのドキュメントの相対リンクには ``L()`` を使用しないでください。

en: ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
ja: URL の場合は ``U()``。たとえば、``See U(https://www.ansible.com/products/automation-platform) for an overview.`` となります。

en: ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``.  Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
ja: (Ansible 2.10 に含まれる) 見出しと相互参照用 ``R()`` (例: ``See R(Cisco IOS Platform Guide,ios_platform_options)``)。クロス参照に RST アンカーを使用します。詳細は、:ref:`adding_anchors_rst` を参照してください。

en: ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
ja: ``M()`` モジュール名。たとえば ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)`` になります。

en: There are also some macros which do not create links but we use them to display certain types of content in a uniform way:
ja: リンクを作成しないものの、そのマクロを使用して、特定のタイプのコンテンツを統一して表示します。

en: ``I()`` for option names. For example: ``Required if I(state=present).``  This is italicized in the documentation.
ja: オプション名の場合は ``I()``。たとえば ``Required if I(state=present).`` です。これは、ドキュメントではイタリック体で示されています。

en: ``C()`` for files, option values, and inline code. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.`` or ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.``  This displays with a mono-space font in the documentation.
ja: ファイル、オプション値、およびインラインコードの場合は ``C()`` (例 ``If not set the environment variable C(ACME_PASSWORD) will be used.`` または ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.``)。これは、ドキュメントでは Monospace フォントと表示されます。

en: ``B()`` currently has no standardized usage.  It is displayed in boldface in the documentation.
ja: ``B()`` は、現在、標準化された使用はありません。このドキュメントには太字が表示されます。

en: ``HORIZONTALLINE`` is used sparingly as a separator in long descriptions.  It becomes a horizontal rule (the ``<hr>`` html tag) in the documentation.
ja: ``HORIZONTALLINE`` は、長い説明では、区切り文字として慎重に使用されており、ドキュメント内の水平ルール (``<hr>`` html タグ) になります。

en: For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links.
ja: コレクション内のモジュールとドキュメント間のリンクについては、上記のオプションのいずれかを使用することができます。コレクション外のリンクについては、利用可能な場合は ``R()`` を使用します。利用できない場合は、(相対リンクではなく) 完全な URL で ``U()`` または ``L()`` を使用します。モジュールの場合は、例のように、FQCN または ``ansible.builtin`` で ``M()`` を使用します。独自のドキュメントサイトを作成する場合は、`intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ を使用して ``R()`` および ``M()`` を正しいリンクに変換する必要があります。

en: To refer to a group of modules in a collection, use ``R()``.  When a collection is not the right granularity, use ``C(..)``:
ja: コレクション内のモジュールのグループを参照するには、``R()`` を使用します。コレクションが適切な粒度ではない場合は、``C(..)`` を使用します。

en: Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description.
ja: ``seealso`` の方が目立つため、一般的な参照にはノートの使用や説明へのリンクよりも、``seealso`` を使用することが推奨されます。

en: Documentation fragments
ja: ドキュメントフラグメント

en: If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``kubernetes.core.k8s_auth_options``).
ja: 複数の関連モジュールを記述している場合は、認証の詳細やファイルモードの設定、``notes:`` や``seealso:`` のエントリーなど、共通のドキュメントを共有していることがあります。そのような情報を各モジュールの ``DOCUMENTATION`` ブロックに複製するのではなく、doc_fragment プラグインとして一度保存し、各モジュールのドキュメントで使用することができます。Ansible では、共有ドキュメントフラグメントは、`lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ の ``ModuleDocFragment`` クラス、またはコレクションの同等のディレクトリーに含まれています。ドキュメントフラグメントを含めるには、モジュールのドキュメントに ``extends_documentation_fragment: FRAGMENT_NAME`` を追加します。FRAGMENT_NAME には、完全修飾されたコレクション名を使用します (例: ``kubernetes.core.k8s_auth_options``)。

en: Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment.
ja: モジュールがドキュメントフラグメントのアイテムを使用するのは、そのフラグメントをインポートする既存のモジュールと同じように動作して、ドキュメント化されたすべてのインターフェースをモジュールが実装する場合のみです。目標は、ドキュメントフラグメントからインポートされたアイテムが、ドキュメントフラグメントをインポートする別のモジュールで使用された場合と同じように動作することです。

en: By default, only the ``DOCUMENTATION`` property from a doc fragment is inserted into the module documentation. It is possible to define additional properties in the doc fragment in order to import only certain parts of a doc fragment or mix and match as appropriate. If a property is defined in both the doc fragment and the module, the module value overrides the doc fragment.
ja: デフォルトでは、ドキュメントフラグメントの ``DOCUMENTATION`` プロパティーがモジュールのドキュメントに挿入されます。ドキュメントフラグメントの特定の部分のみをインポートするため、または必要に応じて組み合わせて一致させるために、ドキュメントフラグメントに追加のプロパティーを定義することができます。プロパティーがドキュメントフラグメントとモジュールの両方で定義されている場合、モジュール値はドキュメントフラグメントを上書きします。

en: Here is an example doc fragment named ``example_fragment.py``:
ja: 以下は、``example_fragment.py`` という名前のドキュメントフラグメントの例です。

en: To insert the contents of ``OTHER`` in a module:
ja: ``OTHER`` の内容をモジュールに挿入するには、以下を行います。

en: Or use both :
ja: または、以下の両方を使用してください。

en: Since Ansible 2.8, you can have user-supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin.
ja: Ansible 2.8 以降、その他のプラグインと同様に、プレイやロールに隣接する ``doc_fragments`` ディレクトリーを使用することで、ユーザーが提供するドキュメントフラグメントを設定できます。

en: For example, all AWS modules should include:
ja: たとえば、すべての AWS モジュールには以下を含める必要があります。

en: :ref:`docfragments_collections` describes how to incorporate documentation fragments in a collection.
ja: 「:ref:`docfragments_collections`」では、コレクションにドキュメントのフラグメントを組み込む方法を説明します。

en: EXAMPLES block
ja: EXAMPLES ブロック

en: After the shebang, the UTF-8 coding, the copyright line, the license section, and the ``DOCUMENTATION`` block comes the ``EXAMPLES`` block. Here you show users how your module works with real-world examples in multi-line plain-text YAML format. The best examples are ready for the user to copy and paste into a playbook. Review and update your examples with every change to your module.
ja: シバンの後、UTF-8 コーディング、著作権表示、ライセンスセクション、および ``DOCUMENTATION``ブロックの後に ``EXAMPLES`` ブロックが続きます。ここでは、モジュールが実際の例で複数行のプレーンテキスト YAML 形式でどのように機能するかをユーザーに示します。最良の例は、ユーザーがコピーして Playbook に貼り付ける準備ができています。モジュールに変更を加えるたびに、例を確認して更新してください。

en: Per playbook best practices, each example should include a ``name:`` line::
ja: Playbook のベストプラクティスに基づき、各例には ``name:`` 行が必要です。

en: The ``name:`` line should be capitalized and not include a trailing dot.
ja: ``name:`` 行は大文字にし、末尾のドットは含めないでください。

en: Use a fully qualified collection name (FQCN) as a part of the module's name like in the example above. For modules in ``ansible-core``, use the ``ansible.builtin.`` identifier, for example ``ansible.builtin.debug``.
ja: 上記の例のように、モジュール名の一部として完全修飾コレクション名 (FQCN) を使用します。``ansible-core`` のモジュールの場合は、``ansible.builtin.`` 識別子 (たとえば ``ansible.builtin.debug``) を使用します。

en: If your examples use boolean options, use yes/no values. Since the documentation generates boolean values as yes/no, having the examples use these values as well makes the module documentation more consistent.
ja: サンプルでブール値オプションを使用する場合は、yes/no の値を使用します。ドキュメントによりブール値が yes/no として生成されるため、このサンプルではこれらの値が使用されており、モジュールドキュメントの一貫性が保たれます。

en: If your module returns facts that are often needed, an example of how to use them can be helpful.
ja: モジュールが必要なファクトを返すと、その使用方法の例が便利です。

en: RETURN block
ja: RETURN ブロック

en: After the shebang, the UTF-8 coding, the copyright line, the license section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
ja: シバン、UTF-8コーディング、著作権表示、ライセンスセクション、``DOCUMENTATION`` ブロックおよび ``EXAMPLES`` ブロックの後に、``RETURN`` ブロックが続きます。このセクションでは、モジュールが他のモジュールで使用するために返す情報を説明します。

en: If your module doesn't return anything (apart from the standard returns), this section of your module should read: ``RETURN = r''' # '''`` Otherwise, for each value returned, provide the following fields. All fields are required unless specified otherwise.
ja: モジュールが何も返さない場合は (標準の戻り値とは異なり)、モジュールのこのセクションは「``RETURN = r''' # '''``」を読み取る必要があります。それ以外の場合は、返された各値に以下のフィールドを指定します。特に指定がない場合はすべてのフィールドが必要になります。

en: Name of the returned field.
ja: 返されるフィールドの名前。

en: Detailed description of what this value represents. Capitalized and with trailing dot.
ja: この値が表す内容の詳細な説明。大文字で、末尾のドットを使用します。

en: When this value is returned, such as ``always``, ``changed`` or ``success``. This is a string and can contain any human-readable content.
ja: ``always``、``changed``、``success`` などのこの値が返されると、これは文字列となり、人間が判読できるコンテンツを含めることができます。

en: Data type.
ja: データ型。

en: If ``type='list'``, specifies the data type of the list's elements.
ja: ``type='list'`` の場合は、リストの要素のデータタイプを指定します。

en: One or more examples.
ja: 1 つ以上の例。

en: Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field. This is a string, and not a float, for example, ``version_added: '2.3'``.
ja: これは、最初の Ansible リリースの後にこの返された場合にのみ必要です。つまり、これは最上位レベルの `version_added` フィールドよりも大きくなります。これは浮動小数点ではなく、文字列です (例: ``version_added: '2.3'``)。

en: Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements: dict``, or if you really have to, ``type: complex``, and repeat the elements above for each sub-field.
ja: 任意です。ネストされた戻り値を記述するには、``type: dict`` または ``type: list``/``elements: dict`` を設定するか、本当に必要であれば ``type: complex`` を設定し、各サブフィールドに対して上記の要素を繰り返します。

en: Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field::
ja: 以下の例は、``RETURN`` セクションを 3 つの単純なフィールドと、複雑なネストされたフィールドを持つ 2 つのセクションです。

en: Python imports
ja: Python のインポート

en: After the shebang, the UTF-8 coding, the copyright line, the license, and the sections for ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN``, you can finally add the python imports. All modules must use Python imports in the form:
ja: シバンの後には、UTF-8 コード行、著作権行、ライセンス、および ``DOCUMENTATION``、``EXAMPLES``、および ``RETURN`` のセクションが最後に python インポートを追加できます。すべてのモジュールは、この形式の Python インポートを使用する必要があります。

en: The use of "wildcard" imports such as ``from module_utils.basic import *`` is no longer allowed.
ja: ``from module_utils.basic import *`` などの「ワイルドカード」インポートの使用は許可されなくなりました。

en: Testing module documentation
ja: モジュールドキュメンテーションのテスト

en: To test Ansible documentation locally please :ref:`follow instruction<testing_module_documentation>`.
ja: Ansible ドキュメントをローカルでテストするには、「:ref:`指示に従う<testing_module_documentation>`」を参照してください。

en: Developing Ansible modules
ja: Ansible モジュールの開発

en: A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the :command:`ansible` or :command:`ansible-playbook` programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting.
ja: モジュールは、Ansible がローカルまたはリモートのいずれかで実行する再利用可能なスタンドアロンスクリプトです。モジュールは、ローカルマシン、API、またはリモートシステムと対話し、データベースパスワードの変更やクラウドインスタンスの起動などの特定のタスクを実行します。各モジュールは、Ansible API または :command:`ansible` または :command:`ansible-playbook` プログラムで使用できます。モジュールは定義されたインターフェースを提供し、引数を受け入れ、終了前に JSON 文字列を stdout に出力して Ansible に情報を返します。

en: If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see :ref:`developing_locally`.
ja: コレクションにある数千の Ansible モジュールで利用できない機能が必要な場合は、独自のカスタムモジュールを簡単に作成できます。ローカルで使用するためのモジュールを作成する場合は、任意のプログラミング言語を選択して、独自のルールに従うようにすることができます。本トピックを使用して、Python で Ansible モジュールを作成する方法を説明します。モジュールを作成したら、Ansible が検出および実行できるように、これを適切なディレクトリーにローカルに追加する必要があります。ローカルでモジュールを追加する方法は、「:ref:`developing_locally`」を参照してください。

en: Preparing an environment for developing Ansible modules
ja: Ansible モジュール開発用の環境の準備

en: Installing prerequisites via apt (Ubuntu)
ja: apt (Ubuntu) を使用した前提条件のインストール

en: Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):
ja: 依存関係のため (例: ansible -> paramiko -> pynacl -> libffi)。

en: Installing prerequisites via yum (CentOS)
ja: yum を使用した前提条件のインストール (CentOS)

en: Creating a development environment (platform-agnostic steps)
ja: 開発環境の作成 (プラットフォームに依存しない手順)

en: Clone the Ansible repository: ``$ git clone https://github.com/ansible/ansible.git``
ja: Ansible リポジトリーのクローンを作成します (``$ git clone https://github.com/ansible/ansible.git``)。

en: Change directory into the repository root dir: ``$ cd ansible``
ja: ディレクトリーをリポジトリーの root ディレクトリーに変更します (``$ cd ansible``)。

en: Create a virtual environment: ``$ python3 -m venv venv`` (or for Python 2 ``$ virtualenv venv``. Note, this requires you to install the virtualenv package: ``$ pip install virtualenv``)
ja: 仮想環境を作成します (``$ python3 -m venv venv``) (Python 2 の場合は ``$ virtualenv venv`` です。これには、virtualenv パッケージ ``$ pip install virtualenv`` をインストールする必要があります。

en: Activate the virtual environment: ``$ . venv/bin/activate``
ja: 仮想環境をアクティベートします (``$ . venv/bin/activate``)。

en: Install development requirements: ``$ pip install -r requirements.txt``
ja: 開発要件をインストールします (``$ pip install -r requirements.txt``)。

en: Run the environment setup script for each new dev shell process: ``$ . hacking/env-setup``
ja: 新規 dev シェルプロセスごとに環境設定スクリプトを実行します (``$ . hacking/env-setup``)。

en: After the initial setup above, every time you are ready to start developing Ansible you should be able to just run the following from the root of the Ansible repo: ``$ . venv/bin/activate && . hacking/env-setup``
ja: 上記の初期設定後、Ansible の開発準備ができるたびに、Ansible リポジトリーのルートから ``$ . venv/bin/activate && . hacking/env-setup`` を実行できるはずです。

en: Creating an info or a facts module
ja: 情報またはファクトモジュールの作成

en: Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules. If you find yourself trying to add ``state: info`` or ``state: list`` to an existing module, that is often a sign that a new dedicated ``_facts`` or ``_info`` module is needed.
ja: Ansible は、ファクトモジュールを使用してターゲットマシンに関する情報を収集し、info モジュールを使用して他のオブジェクトやファイルに関する情報を収集します。既存のモジュールに ``state: info`` または ``state: list`` を追加しようとする際、多くの場合、これが新規の専用 ``_facts`` モジュールまたは ``_info`` モジュールが必要になるという署名になります。

en: In Ansible 2.8 and onwards, we have two type of information modules, they are ``*_info`` and ``*_facts``.
ja: Ansible 2.8 以降では、2 種類の情報モジュール (``*_info`` および ``*_facts``) があります。

en: If a module is named ``<something>_facts``, it should be because its main purpose is returning ``ansible_facts``. Do not name modules that do not do this with ``_facts``. Only use ``ansible_facts`` for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed.
ja: モジュールの名前が ``<something>_facts`` なのは、``ansible_facts`` を返すことが主な目的だからです。これは、``_facts`` でこれを行わないモジュールに名前を付けないでください。ネットワークインターフェースやその設定や、オペレーティングシステムやインストールされているプログラムなど、ホストマシンに固有の情報には ``ansible_facts`` のみを使用してください。

en: Modules that query/return general information (and not ``ansible_facts``) should be named ``_info``. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs.
ja: (``ansible_facts`` ではなく) 一般情報をクエリーまたは返すモジュールの名前は、``_info`` にする必要があります。オンライン/クラウドサービスに関する情報などの一般的な情報は、ホスト以外の固有の情報 (同じホストから同じオンラインサービスの異なるアカウントにアクセスできる)、マシンからアクセス可能な仮想マシンおよびコンテナーに関する情報、または個々のファイルまたはプログラムに関する情報です。

en: Info and facts modules, are just like any other Ansible Module, with a few minor requirements:
ja: info モジュールおよび facts モジュールには、他の Ansible モジュールと同様に、さほど重要ではない要件があります。

en: They MUST be named ``<something>_info`` or ``<something>_facts``, where <something> is singular.
ja: 名前は ``<something>_info`` または ``<something>_facts`` です。<something> は単数になります。

en: Info ``*_info`` modules MUST return in the form of the :ref:`result dictionary<common_return_values>` so other modules can access them.
ja: info の ``*_info`` モジュールは、他のモジュールがアクセスできるように :ref:`結果ディレクトリー<common_return_values>` の形式で返す必要があります。

en: Fact ``*_facts`` modules MUST return in the ``ansible_facts`` field of the :ref:`result dictionary<common_return_values>` so other modules can access them.
ja: fact の ``*_facts`` モジュールは、他のモジュールがそれらにアクセスできるように :ref:`結果ディレクトリー<common_return_values>` の ``ansible_facts`` フィールドに返す必要があります。

en: They MUST support :ref:`check_mode <check_mode_dry>`.
ja: :ref:`check_mode <check_mode_dry>` をサポートする必要があります。

en: They MUST NOT make any changes to the system.
ja: システムに変更を加えないでください。

en: They MUST document the :ref:`return fields<return_block>` and :ref:`examples<examples_block>`.
ja: :ref:`return fields<return_block>` および :ref:`examples<examples_block>` を文書化する必要があります。

en: To create an info module:
ja: info モジュールを作成するには、次を実行します。

en: Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree.
ja: 新しいモジュールの正しいディレクトリーに移動します (``$ cd lib/ansible/modules/``)。コレクションを使用してモジュールを開発する場合は、コレクション開発ツリー内で ``$ cd plugins/modules/`` を実行します。

en: Create your new module file: ``$ touch my_test_info.py``.
ja: 新しいモジュールファイルを作成します (``$ touch my_test_info.py``)。

en: Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code.
ja: 以下の内容を新しい情報モジュールファイルに貼り付けます。これには、:ref:`必須の Ansible 形式およびドキュメント <developing_modules_documenting>`、:ref:`モジュールオプションを宣言する単純な引数仕様 <argument_spec>`、およびサンプルコードが含まれます。

en: Modify and extend the code to do what you want your new info module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code.
ja: 新しい情報モジュールが実行することを行えるようにコードを変更し、拡張します。余計なものが入っていないモジュールコードや、簡潔なモジュールコードの作成に関するヒントは、「:ref:`プログラミングのヒント <developing_modules_best_practices>`」ページおよび「:ref:`Python 3 互換性 <developing_python_3>`」ページを参照してください。

en: Use the same process to create a facts module.
ja: 同じプロセスを使用してファクトモジュールを作成します。

en: Creating a module
ja: モジュールの作成

en: To create a module:
ja: モジュールを作成するには、以下を行います。

en: Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing a module in a :ref:`collection <developing_collections>`, ``$ cd plugins/modules/`` inside your collection development tree.
ja: 新しいモジュールの正しいディレクトリーに移動します (``$ cd lib/ansible/modules/``)。:ref:`コレクション <developing_collections>` でモジュールを開発する場合は、コレクション開発ツリー内で ``$ cd plugins/modules/`` を実行します。

en: Create your new module file: ``$ touch my_test.py``.
ja: 新しいモジュールファイルを作成します (``$ touch my_test.py``)。

en: Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code.
ja: 以下の内容を新しいモジュールファイルに貼り付けます。これには、:ref:`必須の Ansible 形式およびドキュメント <developing_modules_documenting>`、:ref:`モジュールオプションを宣言する単純な引数仕様 <argument_spec>`、およびいくつかのサンプルコードが含まれます。

en: Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code.
ja: 新しいモジュールが実行することを行えるようにコードを変更し、拡張します。余計なものが入っていないモジュールコードや、簡潔なモジュールコードの作成に関するヒントは、「:ref:`プログラミングのヒント <developing_modules_best_practices>`」ページおよび」:ref:`Python 3 互換性 <developing_python_3>`」ページを参照してください。

en: Verifying your module code
ja: モジュールコードの確認

en: After you modify the sample code above to do what you want, you can try out your module. Our :ref:`debugging tips <debugging_modules>` will help if you run into bugs as you verify your module code.
ja: 上記のサンプルコードを修正したら、モジュールを試すことができます。:ref:`debugging tips <debugging_modules>` は、モジュールコードを検証する際にバグが発生した場合に役立ちます。

en: Verifying your module code locally
ja: モジュールコードのローカルでの確認

en: If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this:
ja: モジュールがリモートホストを対象にする必要がない場合は、以下のようにコードをローカルで簡単に使用できます。

en: Create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file ``/tmp/args.json`` and add the following content:
ja: 引数ファイルを作成します。これは、モジュールを実行できるようにパラメーターをモジュールに渡す基本的な JSON 構成ファイルです。引数ファイル ``/tmp/args.json`` に名前を付け、以下の内容を追加します。

en: If you are using a virtual environment (which is highly recommended for development) activate it: ``$ . venv/bin/activate``
ja: (開発に非常に推奨されている) 仮想環境を使用している場合は、アクティベートします (``$ . venv/bin/activate``)。

en: Set up the environment for development: ``$ . hacking/env-setup``
ja: 開発用の環境を設定します (``$ . hacking/env-setup``)。

en: Run your test module locally and directly: ``$ python -m ansible.modules.my_test /tmp/args.json``
ja: テストモジュールをローカルで直接実行します (``$ python -m ansible.modules.my_test /tmp/args.json``)。

en: This should return output like this:
ja: これにより、以下のような出力が返されます。

en: Verifying your module code in a playbook
ja: Playbook でのモジュールコードの確認

en: The next step in verifying your new module is to consume it with an Ansible playbook.
ja: 新規モジュールを検証する次のステップは、Ansible Playbook で使用します。

en: Create a playbook in any directory: ``$ touch testmod.yml``
ja: 任意のディレクトリーに Playbook を作成します (``$ touch testmod.yml``)。

en: Add the following to the new playbook file::
ja: 以下を新しい Playbook ファイルに追加します。

en: Run the playbook and analyze the output: ``$ ansible-playbook ./testmod.yml``
ja: Playbook を実行し、出力を分析します (``$ ansible-playbook ./testmod.yml``)。

en: Testing your newly-created module
ja: 新たに作成したモジュールのテスト

en: The following two examples will get you started with testing your module code. Please review our :ref:`testing <developing_testing>` section for more detailed information, including instructions for :ref:`testing module documentation <testing_module_documentation>`, adding :ref:`integration tests <testing_integration>`, and more.
ja: 以下の 2 つの例は、モジュールコードのテストを開始します。:ref:`モジュールのテストのドキュメント <testing_module_documentation>` の手順、:ref:`統合テスト <testing_integration>` の追加などの詳細な情報は、:ref:`テスト <developing_testing>` のセクションを参照してください。

en: Every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the ``unsupported`` alias in `aliases file <https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html>`_.
ja: テストを Ansible CI インフラストラクチャーで実行できない場合でも、新しいモジュールとプラグインには統合テストが必要です。この場合、テストは `aliases file <https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html>`_ の ``unsupported`` エイリアスでマーク付けする必要があります。

en: Performing sanity tests
ja: 健全性テストの実行

en: You can run through Ansible's sanity checks in a container:
ja: Ansible の健全性チェックをコンテナーで実行できます。

en: Note that this example requires Docker to be installed and running. If you'd rather not use a container for this, you can choose to use ``--venv`` instead of ``--docker``.
ja: この例では、Docker をインストールして実行する必要があります。コンテナーを使用しない場合は、``--docker`` の代わりに ``--venv`` を使用できます。

en: You can add unit tests for your module in ``./test/units/modules``. You must first set up your testing environment. In this example, we're using Python 3.5.
ja: モジュールのユニットテストは ``./test/units/modules`` で追加できます。まずテスト環境を設定する必要があります。この例では、Python 3.5 を使用しています。

en: Install the requirements (outside of your virtual environment): ``$ pip3 install -r ./test/lib/ansible_test/_data/requirements/units.txt``
ja: (仮想環境外に) 要件をインストールします (``$ pip3 install -r ./test/lib/ansible_test/_data/requirements/units.txt``)。

en: Run ``. hacking/env-setup``
ja: ``. hacking/env-setup`` を実行します。

en: To run all tests do the following: ``$ ansible-test units --python 3.5``. If you are using a CI environment, these tests will run automatically.
ja: すべてのテストを実行するには、``$ ansible-test units --python 3.5`` を実行します。CI 環境を使用している場合は、これらのテストが自動的に実行されます。

en: Ansible uses pytest for unit testing.
ja: Ansible はユニットテストに pytest を使用します。

en: To run pytest against a single test module, you can run the following command. Ensure that you are providing the correct path of the test module:
ja: 単一のテストモジュールに対して pytest を実行するには、以下のコマンドを実行します。テストモジュールの正しいパスを提供していることを確認してください。

en: Contributing back to Ansible
ja: Ansible への貢献

en: If you would like to contribute to ``ansible-core`` by adding a new feature or fixing a bug, `create a fork <https://help.github.com/articles/fork-a-repo/>`_ of the ansible/ansible repository and develop against a new feature branch using the ``devel`` branch as a starting point. When you have a good working code change, you can submit a pull request to the Ansible repository by selecting your feature branch as a source and the Ansible devel branch as a target.
ja: 新しい機能を追加したりバグを修正したりして、``ansible-core`` に貢献する場合は、ansible/ansible リポジトリーの `create a fork <https://help.github.com/articles/fork-a-repo/>`_ し、開始点として ``devel`` ブランチを使用して新機能ブランチに対して開発します。適切な作業コードも変更がある場合は、機能ブランチをソースとして、およびAnsible devel ブランチをターゲットとして選択し、Ansible リポジトリーにプル要求を送信します。

en: If you want to contribute a module to an :ref:`Ansible collection <contributing_maintained_collections>`, review our :ref:`submission checklist <developing_modules_checklist>`, :ref:`programming tips <developing_modules_best_practices>`, and :ref:`strategy for maintaining Python 2 and Python 3 compatibility <developing_python_3>`, as well as information about :ref:`testing <developing_testing>` before you open a pull request.
ja: モジュールを :ref:`Ansible コレクション <contributing_maintained_collections>` に提供したい場合は、:ref:`提出のチェックアウト <developing_modules_checklist>`、:ref:`プログラムのヒント <developing_modules_best_practices>`、および :ref:`Python 2 および Python 3 の互換性を維持するストラテジー <developing_python_3>` を確認してください。プル要求を作成する前に、:ref:`テスト <developing_testing>` に関する情報も併せて参照してください。

en: The :ref:`Community Guide <ansible_community_guide>` covers how to open a pull request and what happens next.
ja: :ref:`コミュニティーガイド <ansible_community_guide>` では、プル要求を開く方法と、次に実行することを説明します。

en: Communication and development support
ja: 通信および開発のサポート

en: Join the IRC channel ``#ansible-devel`` on `irc.libera.chat <https://libera.chat/>`_ for discussions surrounding Ansible development.
ja: Ansible 開発に取り組むため、`irc.libera.chat <https://libera.chat/>`_ の IRC チャンネル ``#ansible-devel`` に参加します。

en: For questions and discussions pertaining to using the Ansible product, use the ``#ansible`` channel.
ja: Ansible 製品の使用に関する質問および貢献については、``#ansible`` チャンネルを使用します。

en: For more specific IRC channels look at :ref:`Community Guide, Communicating <communication_irc>`.
ja: より具体的な IRC チャンネルは、「:ref:`コミュニティーガイドのコミュニケーション <communication_irc>`」を参照してください。

en: Credit
ja: 謝辞

en: Thank you to Thomas Stringer (`@trstringer <https://github.com/trstringer>`_) for contributing source material for this topic.
ja: このトピックの元となる資料を提供していただいた Thomas Stringer (`@trstringer <https://github.com/trstringer>`_) 氏に感謝の意を示します。

en: Developing Cisco ACI modules
ja: Cisco ACI モジュールの開発

en: This is a brief walk-through of how to create new Cisco ACI modules for Ansible.
ja: Ansible 向けに新しい Cisco ACI モジュールを作成する方法に関する簡単なウォークスルーです。

en: For more information about Cisco ACI, look at the :ref:`Cisco ACI user guide <aci_guide>`.
ja: Cisco ACI の詳細は、「:ref:`Cisco ACI ユーザーガイド <aci_guide>`」を参照してください。

en: What's covered in this section:
ja: 本項で取り上げられている内容:

en: Introduction
ja: はじめに

en: The `cisco.aci collection <https://galaxy.ansible.com/cisco/aci>`_ already includes a large number of Cisco ACI modules, however the ACI object model is huge and covering all possible functionality would easily cover more than 1500 individual modules.
ja: `cisco.aci collection <https://galaxy.ansible.com/cisco/aci>`_ にはすでに多数の Cisco ACI モジュールが含まれていますが、ACI オブジェクトモデルは大きく、すべての機能に対応するため、1500 以上のモジュールを簡単に対応できます。

en: If you need specific functionality, you have 2 options:
ja: 特定の機能が必要な場合は、2 つのオプションがあります。

en: Learn the ACI object model and use the low-level APIC REST API using the :ref:`aci_rest <aci_rest_module>` module
ja: ACI オブジェクトモデルを学習し、「:ref:`aci_rest <aci_rest_module>`」モジュールを使用して低レベルの APIC REST API を使用します。

en: Write your own dedicated modules, which is actually quite easy
ja: 独自の専用モジュールを作成することは、実際には非常に簡単です。

en: A good introduction to the ACI object model.
ja: ACI オブジェクトモデルの優れた概要。

en: Complete reference of the APIC object model.
ja: APIC オブジェクトモデルの完全なリファレンス。

en: Detailed guide on how the APIC REST API is designed and used, incl. many examples.
ja: APIC REST API を設計および使用する方法についての詳細ガイド。多数の例があります。

en: So let's look at how a typical ACI module is built up.
ja: それでは、典型的な ACI モジュールがどのように構築されるかを見てみましょう。

en: ACI module structure
ja: ACI モジュール構造

en: Importing objects from Python libraries
ja: Python ライブラリーからのオブジェクトのインポート

en: The following imports are standard across ACI modules:
ja: 以下のインポートは、ACI モジュール全体で標準のものです。

en: Defining the argument spec
ja: 引数仕様の定義

en: The first line adds the standard connection parameters to the module. After that, the next section will update the ``argument_spec`` dictionary with module-specific parameters. The module-specific parameters should include:
ja: 最初の行は、標準の接続パラメーターをモジュールに追加します。その後、以下のセクションはモジュール固有のパラメーターで ``argument_spec`` ディクショナリーを更新します。モジュール固有のパラメーターには以下が含まれます。

en: the object_id (usually the name)
ja: object_id (通常は名前)

en: the configurable properties of the object
ja: オブジェクトの設定可能なプロパティー

en: the parent object IDs (all parents up to the root)
ja: 親オブジェクト ID (ルートまでのすべての親)

en: only child classes that are a 1-to-1 relationship (1-to-many/many-to-many require their own module to properly manage)
ja: 1 対 1 の関係である子クラスのみ (1 対多/多対多では、独自のモジュールを適切に管理する必要があります)

en: the state
ja: 状態

en: ``state: absent`` to ensure object does not exist
ja: ``state: absent``: オブジェクトが存在しないことを確認する

en: ``state: present`` to ensure the object and configs exist; this is also the default
ja: ``state: present``: オブジェクトと設定が存在することを確認する (デフォルト)

en: ``state: query`` to retrieve information about objects in the class
ja: ``state: query``: クラスのオブジェクトに関する情報を取得する

en: Do not provide default values for configuration arguments. Default values could cause unintended changes to the object.
ja: 設定引数のデフォルト値を指定しないでください。デフォルト値により、オブジェクトへの意図しない変更が生じる可能性があります。

en: Using the AnsibleModule object
ja: AnsibleModule オブジェクトの使用

en: The following section creates an AnsibleModule instance. The module should support check-mode, so we pass the ``argument_spec`` and  ``supports_check_mode`` arguments. Since these modules support querying the APIC for all objects of the module's class, the object/parent IDs should only be required if ``state: absent`` or ``state: present``.
ja: 次のセクションでは、AnsibleModule インスタンスを作成します。モジュールはチェックモードをサポートする必要があるため、``argument_spec`` 引数および ``supports_check_mode`` 引数を渡します。これらのモジュールは、モジュールのクラスのすべてのオブジェクトに対する APIC のクエリーをサポートするため、オブジェクト/親 ID は、``state: absent`` または ``state: present`` の場合に限り必要になります。

en: Mapping variable definition
ja: マッピング変数定義

en: Once the AnsibleModule object has been initiated, the necessary parameter values should be extracted from ``params`` and any data validation should be done. Usually the only params that need to be extracted are those related to the ACI object configuration and its child configuration. If you have integer objects that you would like to validate, then the validation should be done here, and the ``ACIModule.payload()`` method will handle the string conversion.
ja: AnsibleModule オブジェクトが開始されたら、必要なパラメーターの値を ``params`` から抽出し、データの検証を行う必要があります。通常、抽出する必要がある唯一のパラメーターが ACI オブジェクトの設定およびその子設定に関連するパラメーターのみとなります。検証する整数オブジェクトがある場合は、検証を行う必要があります。データ検証はここで行う必要があり、``ACIModule.payload()`` メソッドは変換文字列を処理する必要があります。

en: Using the ACIModule object
ja: ACIModule オブジェクトの使用

en: The ACIModule class handles most of the logic for the ACI modules. The ACIModule extends functionality to the AnsibleModule object, so the module instance must be passed into the class instantiation.
ja: ACIModule クラスは、ACI モジュールのロジックの大部分を処理します。ACIModule は機能を AnsibleModule オブジェクトに拡張するため、モジュールインスタンスをクラスのインスタンス化に渡す必要があります。

en: The ACIModule has six main methods that are used by the modules:
ja: ACIModule には、モジュールによって使用される 6 つの主なメソッドがあります。

en: The first two methods are used regardless of what value is passed to the ``state`` parameter.
ja: 最初の 2 つのメソッドは、``state`` パラメーターに渡される値に関係なく使用されます。

en: Constructing URLs
ja: URL の構築

en: The ``construct_url()`` method is used to dynamically build the appropriate URL to interact with the object, and the appropriate filter string that should be appended to the URL to filter the results.
ja: ``construct_url()`` メソッドは、オブジェクトと対話するために適切な URL と、URL に追加して結果にフィルターを設定する適切なフィルター文字列を動的に構築するのに使用されます。

en: When the ``state`` is not ``query``, the URL is the base URL to access the APIC plus the distinguished name to access the object. The filter string will restrict the returned data to just the configuration data.
ja: ``state`` が ``query`` でない場合、URL は APIC にアクセスするベース URL と、オブジェクトにアクセスするための識別名です。フィルター文字列は返されたデータを設定データにのみ制限します。

en: When ``state`` is ``query``, the URL and filter string used depends on what parameters are passed to the object. This method handles the complexity so that it is easier to add new modules and so that all modules are consistent in what type of data is returned.
ja: ``state`` が ``query`` される場合、使用される URL およびフィルター文字列は、オブジェクトに渡されるパラメーターによって異なります。この方法は複雑性を処理するため、新しいモジュールの追加が容易になります。また、すべてのモジュールがどのタイプのデータを返すかに一貫性を持たせるようにします。

en: Our design goal is to take all ID parameters that have values, and return the most specific data possible. If you do not supply any ID parameters to the task, then all objects of the class will be returned. If your task does consist of ID parameters sed, then the data for the specific object is returned. If a partial set of ID parameters are passed, then the module will use the IDs that are passed to build the URL and filter strings appropriately.
ja: この設計の目的は、値があるすべての ID パラメーターを取り、最も具体的なデータを返すことです。ID パラメーターをタスクに指定しないと、クラスのすべてのオブジェクトが返されます。タスクが ID パラメーター sed で構成されている場合は、特定のオブジェクトのデータが返されます。ID パラメーターの一部が渡されると、モジュールは URL およびフィルター文字列を適切にビルドするために渡された ID を使用します。

en: The ``construct_url()`` method takes 2 required arguments:
ja: ``construct_url()`` メソッドは、必要な引数を 2 つ取ります。

en: **self** - passed automatically with the class instance
ja: **self** - クラスインスタンスで自動的に渡されます。

en: **root_class** - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
ja: **root_class**: ``aci_class`` キー、``aci_rn`` キー、``target_filter`` キー、および ``module_object`` キーで構成されるディクショナリー

en: **aci_class**: The name of the class used by the APIC, for example ``fvTenant``
ja: **aci_class**: APIC が使用するクラス名 (例: ``fvTenant``)

en: **aci_rn**: The relative name of the object, for example ``tn-ACME``
ja: **aci_rn**: オブジェクトの相対名 (例: ``tn-ACME``)

en: **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, for example ``{'name': 'ACME'}``
ja: **target_filter**: エントリーのサブセットを選択するクエリー文字列を構成するキーと値のペアを持つディクショナリー (例: ``{'name': 'ACME'}``)

en: **module_object**: The particular object for this class, for example ``ACME``
ja: **module_object**: このクラスの特定のオブジェクト (例: ``ACME``)

en: Example:
ja: 例:

en: Some modules, like ``aci_tenant``, are the root class and so they would not need to pass any additional arguments to the method.
ja: ``aci_tenant`` などの一部のモジュールは root クラスであるため、メソッドに追加の引数を渡す必要はありません。

en: The ``construct_url()`` method takes 4 optional arguments, the first three imitate the root class as described above, but are for child objects:
ja: ``construct_url()`` メソッドは、4 つの任意の引数を取ります。最初の 3 つの引数が上記のように root クラスを模倣しますが、これは子オブジェクト用です。

en: subclass_1 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
ja: subclass_1 - ``aci_class`` キー、``aci_rn`` キー、``target_filter`` キー、および ``module_object`` キーで構成されるディクショナリー

en: Example: Application Profile Class (AP)
ja: 例: Application Profile Class (AP)

en: subclass_2 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
ja: subclass_2 - ``aci_class`` キー、``aci_rn`` キー、``target_filter`` キー、および ``module_object`` キーで構成されるディクショナリー

en: Example: End Point Group (EPG)
ja: 例: エンドポイントグループ (EPG)

en: subclass_3 - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
ja: subclass_3 - ``aci_class`` キー、``aci_rn`` キー、``target_filter`` キー、および ``module_object`` キーで構成されるディクショナリー

en: Example: Binding a Contract to an EPG
ja: 例: EPG への契約のバインド

en: child_classes - The list of APIC names for the child classes supported by the modules.
ja: child_classes - モジュールがサポートする子クラスの APIC 名のリスト。

en: This is a list, even if it is a list of one
ja: 1 つのリストであっても、これはリストです

en: These are the unfriendly names used by the APIC
ja: これらは、APIC が使用する分かりにくい名前です。

en: These are used to limit the returned child_classes when possible
ja: 可能な場合は、返された child_classes を制限するのに使用されます。

en: Example: ``child_classes=['fvRsBDSubnetToProfile', 'fvRsNdPfxPol']``
ja: 例: ``child_classes=['fvRsBDSubnetToProfile', 'fvRsNdPfxPol']``

en: Sometimes the APIC will require special characters ([, ], and -) or will use object metadata in the name ("vlanns" for VLAN pools); the module should handle adding special characters or joining of multiple parameters in order to keep expected inputs simple.
ja: APIC は、特殊文字 ([, ]、および -) を要求したり、名前にオブジェクトのメタデータ (「VLAN」プールの場合は「vlanns」) を使用したりすることがあります。モジュールは、予想される入力の単純さに保つために、特殊文字の追加または複数のパラメーターの結合を処理する必要があります。

en: Getting the existing configuration
ja: 既存設定の取得

en: Once the URL and filter string have been built, the module is ready to retrieve the existing configuration for the object:
ja: URL およびフィルター文字列が構築されると、モジュールはオブジェクトの既存の設定を取得できるようになります。

en: ``state: present`` retrieves the configuration to use as a comparison against what was entered in the task. All values that are different than the existing values will be updated.
ja: ``state: present`` は、タスクに入力した値と比較として使用する設定を取得します。既存の値とは異なる値はすべて更新されます。

en: ``state: absent`` uses the existing configuration to see if the item exists and needs to be deleted.
ja: ``state: absent`` は、既存の設定を使用して項目が存在し、削除する必要があるかどうかを確認します。

en: ``state: query`` uses this to perform the query for the task and report back the existing data.
ja: ``state: query`` は、これを使用してタスクのクエリーを実行し、既存のデータを報告します。

en: When state is present
ja: state が present の場合

en: When ``state: present``, the module needs to perform a diff against the existing configuration and the task entries. If any value needs to be updated, then the module will make a POST request with only the items that need to be updated. Some modules have children that are in a 1-to-1 relationship with another object; for these cases, the module can be used to manage the child objects.
ja: ``state: present`` の場合、モジュールは既存の設定とタスクエントリーに対して diff を実行する必要があります。値を更新する必要がある場合、モジュールは更新が必要なアイテムのみが含まれる POST 要求を行います。モジュールによっては、別のオブジェクトと 1-to-1 の関係にある子があります。これらの場合、モジュールは子オブジェクトを管理するために使用できます。

en: Building the ACI payload
ja: ACI ペイロードの構築

en: The ``aci.payload()`` method is used to build a dictionary of the proposed object configuration. All parameters that were not provided a value in the task will be removed from the dictionary (both for the object and its children). Any parameter that does have a value will be converted to a string and added to the final dictionary object that will be used for comparison against the existing configuration.
ja: ``aci.payload()`` メソッドは、提案されたオブジェクト設定のディクショナリー構築に使用されます。タスクで値が提供されていないパラメーターはすべてディクショナリー (オブジェクトとその子の両方) から削除されます。値のあるパラメーターは文字列に変換され、既存の設定との比較に使用される最終ディクショナリーオブジェクトに追加されます。

en: The ``aci.payload()`` method takes two required arguments and 1 optional argument, depending on if the module manages child objects.
ja: ``aci.payload()`` メソッドは、モジュールが子オブジェクトを管理するかどうかに応じて、2 つの必須引数と、1 つの任意の引数を取ります。

en: ``aci_class`` is the APIC name for the object's class, for example ``aci_class='fvBD'``
ja: ``aci_class`` は、オブジェクトのクラスの APIC 名です。たとえば、``aci_class='fvBD'`` になります。

en: ``class_config`` is the appropriate dictionary to be used as the payload for the POST request
ja: ``class_config`` は POST 要求のペイロードとして使用する適切なディクショナリーです。

en: The keys should match the names used by the APIC.
ja: キーは APIC で使用される名前と一致する必要があります。

en: The values should be the corresponding value in ``module.params``; these are the variables defined above
ja: ``module.params`` の対応する値でなければなりません。これらは上で定義される変数です

en: ``child_configs`` is optional, and is a list of child config dictionaries.
ja: ``child_configs`` は任意であり、子設定のディクショナリーの一覧です。

en: The child configs include the full child object dictionary, not just the attributes configuration portion.
ja: 子設定には、属性設定部分だけでなく、完全な子オブジェクトディクショナリーが含まれます。

en: The configuration portion is built the same way as the object.
ja: 設定部分は、オブジェクトと同じ方法で構築されます。

en: Performing the request
ja: 要求の実行

en: The ``get_diff()`` method is used to perform the diff, and takes only one required argument, ``aci_class``. Example: ``aci.get_diff(aci_class='fvBD')``
ja: ``get_diff()`` メソッドは diff を実行し、必要な引数 ``aci_class`` を 1 つだけ取ります。たとえば ``aci.get_diff(aci_class='fvBD')`` です。

en: The ``post_config()`` method is used to make the POST request to the APIC if needed. This method doesn't take any arguments and handles check mode. Example: ``aci.post_config()``
ja: ``post_config()`` メソッドは、必要に応じて APIC への POST 要求を行うために使用されます。このメソッドは引数を受け付けず、チェックモードを処理します。以下に例を示します。たとえば、``aci.post_config()`` になります。

en: Example code
ja: サンプルコード

en: When state is absent
ja: state が absent の場合

en: If the task sets the state to absent, then the ``delete_config()`` method is all that is needed. This method does not take any arguments, and handles check mode.
ja: タスクが state を absent に設定すると、``delete_config()`` メソッドのみが必要になります。このメソッドは引数を取らず、チェックモードを処理します。

en: Exiting the module
ja: モジュールの終了

en: To have the module exit, call the ACIModule method ``exit_json()``. This method automatically takes care of returning the common return values for you.
ja: モジュールを終了するには、ACIModule メソッド ``exit_json()`` を呼び出します。このメソッドは、一般的な戻り値を返すことを自動的に行います。

en: Testing ACI library functions
ja: ACI ライブラリー関数のテスト

en: You can test your ``construct_url()`` and ``payload()`` arguments without accessing APIC hardware by using the following python script:
ja: 以下の python スクリプトを使用して、APIC ハードウェアにアクセスせずに ``construct_url()`` 引数および ``payload()`` 引数をテストすることができます。

en: This will result in:
ja: これにより、以下が生成されます。

en: Testing for sanity checks
ja: 健全性チェックのテスト

en: You can run from your fork something like:
ja: 次のようなフォークから実行できます。

en: Information on how to build sanity tests.
ja: 健全性テストを構築する方法に関する情報

en: Testing ACI integration tests
ja: ACI 統合テストのテスト

en: You can run this:
ja: 以下を実行できます。

en: You may need to add ``--python 2.7`` or ``--python 3.6`` in order to use the correct python version for performing tests.
ja: テストの実行に適切な python バージョンを使用するには、``--python 2.7`` または ``--python 3.6`` を追加しないといけない場合があります。

en: You may want to edit the used inventory at *test/integration/inventory.networking* and add something like:
ja: *test/integration/inventory.networking* で使用されたインベントリーを編集し、以下のように追加することもできます。

en: Information on how to build integration tests.
ja: 統合テストの構築方法に関する情報。

en: Testing for test coverage
ja: テストカバレージのテスト

en: Windows module development walkthrough
ja: Windows モジュール開発ウォークスルー

en: In this section, we will walk through developing, testing, and debugging an Ansible Windows module.
ja: 本セクションでは、Ansible Windows モジュールの開発、テスト、およびデバッグの開発手順 (ウォークスルー) を説明します。

en: Because Windows modules are written in Powershell and need to be run on a Windows host, this guide differs from the usual development walkthrough guide.
ja: Windows モジュールは Powershell で書かれており、Windows ホスト上で実行する必要があるため、このガイドは通常の開発ウォークスルーガイドとは異なります。

en: Windows environment setup
ja: Windows 環境の設定

en: Unlike Python module development which can be run on the host that runs Ansible, Windows modules need to be written and tested for Windows hosts. While evaluation editions of Windows can be downloaded from Microsoft, these images are usually not ready to be used by Ansible without further modification. The easiest way to set up a Windows host so that it is ready to by used by Ansible is to set up a virtual machine using Vagrant. Vagrant can be used to download existing OS images called *boxes* that are then deployed to a hypervisor like VirtualBox. These boxes can either be created and stored offline or they can be downloaded from a central repository called Vagrant Cloud.
ja: Ansible を実行するホストで実行できる Python モジュール開発とは異なり、Windows ホスト用に Windows モジュールを作成およびテストする必要があります。Windows の評価エディションを Microsoft からダウンロードできますが、通常はこれらのイメージを追加の変更なしで Ansible で使用することはできません。Ansible で使用する準備が整うように Windows ホストを設定する最も簡単な方法は、Vagrant を使用して仮想マシンを設定することにあります。Vagrant を使用すると、*ボックス* と呼ばれる既存の OS イメージをダウンロードし、VirtualBox のようなハイパーバイザーにデプロイされます。これらのボックスは、オフラインで作成および保存するか、Vagrant Cloud と呼ばれる中央リポジトリーからダウンロードできます。

en: This guide will use the Vagrant boxes created by the `packer-windoze <https://github.com/jborean93/packer-windoze>`_ repository which have also been uploaded to `Vagrant Cloud <https://app.vagrantup.com/boxes/search?utf8=%E2%9C%93&sort=downloads&provider=&q=jborean93>`_. To find out more info on how these images are created, please go to the GitHub repo and look at the ``README`` file.
ja: 本ガイドでは、`packer-windoze <https://github.com/jborean93/packer-windoze>`_ リポジトリーにより作成された Vagrant ボックスを使用します。これは、`Vagrant Cloud <https://app.vagrantup.com/boxes/search?utf8=%E2%9C%93&sort=downloads&provider=&q=jborean93>`_ にアップロードされました。これらの画像がどのように作成されるかについての詳細は、GitHub リポジトリーで ``README`` ファイルを確認してください。

en: Before you can get started, the following programs must be installed (please consult the Vagrant and VirtualBox documentation for installation instructions):
ja: 作業を開始する前に、以下のプログラムをインストールする必要があります (インストール方法は Vagrant および VirtualBox のドキュメントを参照してください)。

en: Create a Windows server in a VM
ja: 仮想マシンで Windows サーバーを作成

en: To create a single Windows Server 2016 instance, run the following:
ja: 1 つの Windows Server 2016 インスタンスを作成するには、次のコマンドを実行します。

en: This will download the Vagrant box from Vagrant Cloud and add it to the local boxes on your host and then start up that instance in VirtualBox. When starting for the first time, the Windows VM will run through the sysprep process and then create a HTTP and HTTPS WinRM listener automatically. Vagrant will finish its process once the listeners are online, after which the VM can be used by Ansible.
ja: これにより、Vagrant Cloud から Vagrant ボックスをダウンロードし、ホストのローカルボックスに追加して、VirtualBox でそのインスタンスを起動します。初めて起動すると、Windows 仮想マシンが sysprep プロセスを介して実行し、HTTP および HTTPS WinRM リスナーを自動的に作成します。Vagrant は、リスナーがオンラインになるとプロセスを終了します。その後、Ansible で仮想マシンを使用できるようになります。

en: Create an Ansible inventory
ja: Ansible インベントリーの作成

en: The following Ansible inventory file can be used to connect to the newly created Windows VM:
ja: 以下の Ansible インベントリーファイルを使用して、新しく作成した Windows 仮想マシンに接続できます。

en: The port ``55986`` is automatically forwarded by Vagrant to the Windows host that was created, if this conflicts with an existing local port then Vagrant will automatically use another one at random and display show that in the output.
ja: ポート ``55986`` は、Vagrant によって作成された Windows ホストに自動的に転送されます。これが既存のローカルポートと競合する場合、Vagrant は自動的に別のポートをランダムに使用し、出力にそれを表示します。

en: The OS that is created is based on the image set. The following images can be used:
ja: 作成される OS はイメージセットに基づいています。次のイメージを使用できます。

en: When the host is online, it can accessible by RDP on ``127.0.0.1:3389`` but the port may differ depending if there was a conflict. To get rid of the host, run ``vagrant destroy --force`` and Vagrant will automatically remove the VM and any other files associated with that VM.
ja: ホストがオンラインになったら、``127.0.0.1:3389`` で RDP からアクセスできますが、競合があったかどうかによってポートが異なる場合があります。ホストを取り除くには、``vagrant destroy --force`` を実行すると、Vagrant が、仮想マシンとその仮想マシンに関連付けられたその他のファイルを自動的に削除します。

en: While this is useful when testing modules on a single Windows instance, these host won't work without modification with domain based modules. The Vagrantfile at `ansible-windows <https://github.com/jborean93/ansible-windows/tree/master/vagrant>`_ can be used to create a test domain environment to be used in Ansible. This repo contains three files which are used by both Ansible and Vagrant to create multiple Windows hosts in a domain environment. These files are:
ja: これは、単一の Windows インスタンスでモジュールをテストする際に役立ちますが、これらのホストはドメインベースのモジュールで変更せずに動作しません。`ansible-windows <https://github.com/jborean93/ansible-windows/tree/master/vagrant>`_ の Vagrant を使用して、Ansible で使用するテストドメイン環境を作成できます。このリポジトリーには、Ansible と Vagrant で使用されている 3 つのファイルが含まれ、ドメイン環境で複数の Windows ホストを作成するのに使用できます。このファイルは、以下のようになります。

en: ``Vagrantfile``: The Vagrant file that reads the inventory setup of ``inventory.yml`` and provisions the hosts that are required
ja: ``Vagrantfile``: ``inventory.yml`` のインベントリー設定を読み込んで、必要なホストをプロビジョニングする Vagrant ファイルです。

en: ``inventory.yml``: Contains the hosts that are required and other connection information such as IP addresses and forwarded ports
ja: ``inventory.yml``: 必要なホストと、IP アドレスや転送ポートなどの他の接続情報が含まれています。

en: ``main.yml``: Ansible playbook called by Vagrant to provision the domain controller and join the child hosts to the domain
ja: ``main.yml``: Vagrant に呼び出された Ansible Playbook は、ドメインコントローラーをプロビジョニングし、子ホストをドメインに参加させます。

en: By default, these files will create the following environment:
ja: デフォルトでは、これらのファイルは以下の環境を作成します。

en: A single domain controller running on Windows Server 2016
ja: Windows Server 2016 で実行しているドメインコントローラー 1 つ

en: Five child hosts for each major Windows Server version joined to that domain
ja: ドメインに参加している各 Windows Server のメジャーバージョンの子ホスト 5 台

en: A domain with the DNS name ``domain.local``
ja: DNS 名 ``domain.local`` を持つドメイン

en: A local administrator account on each host with the username ``vagrant`` and password ``vagrant``
ja: 各ホストのローカル管理者アカウント (ユーザー名 ``vagrant`` およびパスワード ``vagrant``)

en: A domain admin account ``vagrant-domain@domain.local`` with the password ``VagrantPass1``
ja: パスワード ``VagrantPass1`` を含むドメイン管理者アカウント ``vagrant-domain@domain.local``

en: The domain name and accounts can be modified by changing the variables ``domain_*`` in the ``inventory.yml`` file if it is required. The inventory file can also be modified to provision more or less servers by changing the hosts that are defined under the ``domain_children`` key. The host variable ``ansible_host`` is the private IP that will be assigned to the VirtualBox host only network adapter while ``vagrant_box`` is the box that will be used to create the VM.
ja: ドメイン名およびアカウントを変更するには、必要な場合に ``inventory.yml`` ファイルの変数 ``domain_*`` を変更することで変更できます。インベントリーファイルは、``domain_children`` キーで定義されるホストを変更して、より少ないサーバーをプロビジョニングするように変更することもできます。ホスト変数 ``ansible_host`` は、VirtualBox ホストに割り当てられるプライベート IP で、ネットワークアダプターのみに割り当てられますが、``vagrant_box`` は仮想マシンの作成に使用するボックスです。

en: Provisioning the environment
ja: 環境のプロビジョニング

en: To provision the environment as is, run the following:
ja: 環境をそのままプロビジョニングするには、次を実行します。

en: Vagrant provisions each host sequentially so this can take some time to complete. If any errors occur during the Ansible phase of setting up the domain, run ``vagrant provision`` to rerun just that step.
ja: Vagrant は各ホストを順番にプロビジョニングするため、完了するまでに時間がかかる場合があります。ドメイン設定の Ansible フェーズ中にエラーが発生した場合は、``vagrant provision`` を実行してそのステップだけを再実行します。

en: Unlike setting up a single Windows instance with Vagrant, these hosts can also be accessed using the IP address directly as well as through the forwarded ports. It is easier to access it over the host only network adapter as the normal protocol ports are used, for example RDP is still over ``3389``. In cases where the host cannot be resolved using the host only network IP, the following protocols can be access over ``127.0.0.1`` using these forwarded ports:
ja: Vagrant で単一の Windows インスタンスをセットアップするのとは異なり、これらのホストは、転送されたポートを介してだけでなく、IP アドレスを使用して直接アクセスすることもできます。ホストのみのネットワークアダプターを使用してアクセスする方が、通常のプロトコルのポートが使用されるため簡単です。たとえば、RDP はまだ ``3389`` でで使用されます。ホストのみのネットワーク IP を使用してホストを解決できない場合、以下のプロトコルは、これらの転送されたポートを使用して ``127.0.0.1`` を介してアクセスできます。

en: Replace ``xx`` with the entry number in the inventory file where the domain controller started with ``00`` and is incremented from there. For example, in the default ``inventory.yml`` file, WinRM over HTTPS for ``SERVER2012R2`` is forwarded over port ``29804`` as it's the fourth entry in ``domain_children``.
ja: ``xx`` を、ドメインコントローラーが ``00`` から開始したインベントリーファイルのエントリー番号に置換えます。値がインクリメントされていきます。たとえば、デフォルトでは、``domain_children`` の 4 番目のエントリーであるため、``inventory.yml`` ファイル (WinRM over HTTPS for ``SERVER2012R2``) がポート ``29804`` 経由で転送されます。

en: While an SSH server is available on all Windows hosts but Server 2008 (non R2), it is not a support connection for Ansible managing Windows hosts and should not be used with Ansible.
ja: SSH サーバーはすべての Windows ホストで利用できますが、Server 2008 (R2 以外) は、Ansible が管理する Windows ホストの管理接続ではなく、Ansible では使用できません。

en: Windows new module development
ja: Windows 新しいモジュール開発

en: When creating a new module there are a few things to keep in mind:
ja: 新しいモジュールを作成する際には、以下の点に留意してください。

en: Module code is in Powershell (.ps1) files while the documentation is contained in Python (.py) files of the same name
ja: モジュールのコードは Powershell (.ps1) ファイルにあり、ドキュメントは同じ名前の Python (.py) ファイルに含まれています。

en: Avoid using ``Write-Host/Debug/Verbose/Error`` in the module and add what needs to be returned to the ``$module.Result`` variable
ja: モジュールでは ``Write-Host/Debug/Verbose/Error`` を使用せず、``$module.Result`` 変数に返す必要のあるものを追加します。

en: To fail a module, call ``$module.FailJson("failure message here")``, an Exception or ErrorRecord can be set to the second argument for a more descriptive error message
ja: モジュールを失敗させるには、``$module.FailJson("failure message here")`` を呼び出して、Exception または ErrorRecord を 2 番目の引数に設定して、より詳細なエラーメッセージを表示できます。

en: You can pass in the exception or ErrorRecord as a second argument to ``FailJson("failure", $_)`` to get a more detailed output
ja: 例外または ErrorRecord を 2 つ目の引数として ``FailJson("failure", $_)`` に渡すと、より詳細な出力を取得できます。

en: Most new modules require check mode and integration tests before they are merged into the main Ansible codebase
ja: ほとんどの新規モジュールには、主要な Ansible コードベースにマージする前にチェックモードと統合テストが必要です。

en: Avoid using try/catch statements over a large code block, rather use them for individual calls so the error message can be more descriptive
ja: 大規模なコードブロックで try/catch 文を使用しないようにし、個別の呼び出しに使用することで、エラーメッセージがより分かりやすくなるようにします。

en: Try and catch specific exceptions when using try/catch statements
ja: Try/catch 文の使用時に特定の例外を試して捕え (キャッチし) ます。

en: Avoid using PSCustomObjects unless necessary
ja: 必要な場合を除き PSCustomObject は使用しないでください。

en: Look for common functions in ``./lib/ansible/module_utils/powershell/`` and use the code there instead of duplicating work. These can be imported by adding the line ``#Requires -Module *`` where * is the filename to import, and will be automatically included with the module code sent to the Windows target when run via Ansible
ja: 重複する作業を行わないように、``./lib/ansible/module_utils/powershell/`` にある共通の関数を探して、そこにあるコードを使用してください。これらの関数は ``#Requires -Module *`` という行を追加することでインポートすることができます。* はインポートするファイル名で、Ansible を介して実行する場合に、自動的に Windows ターゲットに送信されたモジュールコードが含まれています。

en: As well as PowerShell module utils, C# module utils are stored in ``./lib/ansible/module_utils/csharp/`` and are automatically imported in a module execution if the line ``#AnsibleRequires -CSharpUtil *`` is present
ja: PowerShell モジュールユーティリティーの他に、C# モジュールユーティリティーが ``./lib/ansible/module_utils/csharp/`` に本され、``#AnsibleRequires -CSharpUtil *`` 行が存在する場合に、モジュール実行に自動的にインポートされます。

en: C# and PowerShell module utils achieve the same goal but C# allows a developer to implement low level tasks, such as calling the Win32 API, and can be faster in some cases
ja: C# と PowerShell モジュールのユーティリティーは同じ目標を達成しますが、C# を使用すると、開発者は Win32 API の呼び出しなどの低レベルのタスクを実装でき、場合によってはより高速になります。

en: Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if higher minimum Powershell or OS versions are required, ensure the documentation reflects this clearly
ja: このコードが Windows Server 2008 以降の Powershell v3 以降で動作することを確認してください。最小バージョンより新しい Powershell または OS が必要な場合は、ドキュメントにこの内容が明確に反映されていることを確認してください。

en: Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putting ``Set-StrictMode -Version 2.0`` at the top of your dev script
ja: Ansible は、strictmode バージョン 2.0 でモジュールを実行します。必ず、開発スクリプトの冒頭に ``Set-StrictMode -Version 2.0`` と記述して、この機能を有効にしてテストしてください。

en: Favor native Powershell cmdlets over executable calls if possible
ja: 可能であれば、実行可能な呼び出しよりも、ネイティブの Powershell コマンドレットを優先してください。

en: Use the full cmdlet name instead of aliases, for example ``Remove-Item`` over ``rm``
ja: エイリアスの代わりに完全なコマンドレット名を使用してください (例: ``rm`` ではなく ``Remove-Item`` を使用)。

en: Use named parameters with cmdlets, for example ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp``
ja: コマンドレットで名前付きパラメーターを使用します (例： ``Remove-Item C:\temp`` ではなく ``Remove-Item -Path C:\temp`` を使用)。

en: A very basic Powershell module `win_environment <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_environment.ps1>`_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met.
ja: 非常に基本的な Powershell モジュール `win_environment <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_environment.ps1>`_ が、Powershell モジュールのベストプラクティスに組み込まれています。これは、check-mode および diff-support を実装する方法を示し、特定の条件が満たされるとユーザーに警告を表示します。

en: A slightly more advanced module is `win_uri <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_uri.ps1>`_ which additionally shows how to use different parameter types (bool, str, int, list, dict, path) and a selection of choices for parameters, how to fail a module and how to handle exceptions.
ja: もう少し高度なモジュールとしては `win_uri <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_uri.ps1>`_ がありますが、ここで、さまざまなパラメーター型 (bool、str、int、list、dict、path) の使用方法やパラメーターの選択方法、モジュールを失敗させる方法、例外の処理方法などを紹介しています。

en: As part of the new ``AnsibleModule`` wrapper, the input parameters are defined and validated based on an argument spec. The following options can be set at the root level of the argument spec:
ja: 新しい ``AnsibleModule`` ラッパーの一部として、入力パラメーターは引数の仕様に基づいて定義および検証されます。以下のオプションは、引数仕様のルートレベルで設定できます。

en: ``mutually_exclusive``: A list of lists, where the inner list contains module options that cannot be set together
ja: ``mutually_exclusive``: リストのリストで、内側のリストには一緒に設定できないモジュールオプションが含まれています。

en: ``no_log``: Stops the module from emitting any logs to the Windows Event log
ja: ``no_log``: モジュールが Windows イベントログにログを出力しないようにします。

en: ``options``: A dictionary where the key is the module option and the value is the spec for that option
ja: ``options``: キーがモジュールオプションで、値がそのオプションの仕様となるディクショナリーです。

en: ``required_by``: A dictionary where the option(s) specified by the value must be set if the option specified by the key is also set
ja: ``required_by``: キーで指定されたオプションが設定されている場合に、値で指定されたオプションも設定しなければならないディクショナリーです。

en: ``required_if``: A list of lists where the inner list contains 3 or 4 elements;
ja: ``required_if``: 内部リストに 3 つまたは 4 つの要素が含まれるリストの一覧

en: The first element is the module option to check the value against
ja: 最初の要素は、値を確認するモジュールオプションです。

en: The second element is the value of the option specified by the first element, if matched then the required if check is run
ja: 2 つ目の要素は、1 つ目の要素によって指定されるオプションの値です。一致すると必須の if チェックが実行します。

en: The third element is a list of required module options when the above is matched
ja: 3 つ目の要素は、上記が一致した場合に必要なモジュールオプションのリストです。

en: An optional fourth element is a boolean that states whether all module options in the third elements are required (default: ``$false``) or only one (``$true``)
ja: 4 番目の要素 (任意) は、3 番目の要素のモジュールオプションがすべて必要なのか (デフォルト: ``$false``)、1 つだけが必要なのか (``$true``) を示すブール値です。

en: ``required_one_of``: A list of lists, where the inner list contains module options where at least one must be set
ja: ``required_one_of``: 少なくとも 1 つは設定しなければならないモジュールオプションが含まれているリストが記載されるリストです。

en: ``required_together``: A list of lists, where the inner list contains module options that must be set together
ja: ``required_together``: 一緒に設定しなければならないモジュールオプションが含まれているリストが記載されるリストです。

en: ``supports_check_mode``: Whether the module supports check mode, by default this is ``$false``
ja: ``supports_check_mode``: モジュールがチェックモードに対応しているかどうか (デフォルトは ``$false``) を指定します。

en: The actual input options for a module are set within the ``options`` value as a dictionary. The keys of this dictionary are the module option names while the values are the spec of that module option. Each spec can have the following options set:
ja: モジュールの実際の入力オプションは、ディクショナリーとなる ``options`` 値に設定されています。このディクショナリーのキーはモジュールオプション名であり、値はそのモジュールオプションの仕様です。各仕様には、次のオプションを設定できます。

en: ``aliases``: A list of aliases for the module option
ja: ``aliases``: モジュールオプションのエイリアス一覧

en: ``choices``: A list of valid values for the module option, if ``type=list`` then each list value is validated against the choices and not the list itself
ja: ``choices``: モジュールオプションの有効な値のリストです。``type=list`` の場合は、各リストの値が選択したものに対して検証され、リスト自体は検証されません。

en: ``default``: The default value for the module option if not set
ja: ``default``: モジュールオプションのデフォルト値 (設定されていない場合) です。

en: ``deprecated_aliases``: A list of hashtables that define aliases that are deprecated and the versions they will be removed in. Each entry must contain the keys ``name`` and ``collection_name`` with either ``version`` or ``date``
ja: ``deprecated_aliases``: 非推奨となるエイリアスと、そのエイリアスが削除されるバージョンを定義するハッシュテーブルの一覧。各エントリーには、``version`` または ``date`` がある ``name`` キーと ``collection_name`` が含まれている必要があります。

en: ``elements``: When ``type=list``, this sets the type of each list value, the values are the same as ``type``
ja: ``elements``: ``type=list`` の場合は、各リスト値のタイプが設定され、値は ``type`` と同じになります。

en: ``no_log``: Will sanitise the input value before being returned in the ``module_invocation`` return value
ja: ``no_log``: ``module_invocation`` の戻り値で返される前に入力値をサニタイズします。

en: ``removed_in_version``: States when a deprecated module option is to be removed, a warning is displayed to the end user if set
ja: ``removed_in_version``: 非推奨のモジュールオプションがいつ削除されるかを示します。これが設定されている場合は、エンドユーザーに警告が表示されます

en: ``removed_at_date``: States the date (YYYY-MM-DD) when a deprecated module option will be removed, a warning is displayed to the end user if set
ja: ``removed_at_date``: 非推奨のモジュールオプションが削除される日付 (YYYY-MM-DD) を示します。これが設定されている場合は、エンドユーザーに警告が表示されます

en: ``removed_from_collection``: States from which collection the deprecated module option will be removed; must be specified if one of ``removed_in_version`` and ``removed_at_date`` is specified
ja: ``removed_from_collection``: 非推奨のモジュールオプションを削除するコレクションの状態。``removed_in_version`` および ``removed_at_date`` のいずれかが指定されている場合は指定する必要があります。

en: ``required``: Will fail when the module option is not set
ja: ``required``: モジュールオプションが設定されていない場合は失敗します。

en: ``type``: The type of the module option, if not set then it defaults to ``str``. The valid types are;
ja: ``type``: モジュールオプションのタイプです。設定されていない場合は、デフォルトで ``str`` に設定されます。有効なタイプは以下のとおりです。

en: ``bool``: A boolean value
ja: ``bool``: ブール値

en: ``dict``: A dictionary value, if the input is a JSON or key=value string then it is converted to dictionary
ja: ``dict``: ディクショナリーの値。入力が JSON または key=value 文字列の場合は、ディクショナリーに変換されます。

en: ``float``: A float or `Single <https://docs.microsoft.com/en-us/dotnet/api/system.single?view=netframework-4.7.2>`_ value
ja: ``float``: 浮動 または `Single <https://docs.microsoft.com/en-us/dotnet/api/system.single?view=netframework-4.7.2>`_ の値

en: ``int``: An Int32 value
ja: ``int``: Int32 値

en: ``json``: A string where the value is converted to a JSON string if the input is a dictionary
ja: ``json``: 入力がディクショナリーである場合に値が JSON 文字列に変換される文字列

en: ``list``: A list of values, ``elements=<type>`` can convert the individual list value types if set. If ``elements=dict`` then ``options`` is defined, the values will be validated against the argument spec. When the input is a string then the string is split by ``,`` and any whitespace is trimmed
ja: ``list``: 値の一覧 (``elements=<type>``) が設定されている場合は、個々のリスト値タイプを変換できます。``elements=dict`` の場合は、``options`` が定義され、値は引数の仕様に対して検証されます。入力が文字列である場合、文字列は ``,`` で分割され、空白文字はすべてトリミングされます。

en: ``path``: A string where values likes ``%TEMP%`` are expanded based on environment values. If the input value starts with ``\\?\`` then no expansion is run
ja: ``path``: ``%TEMP%`` などの値が環境値に基づいて展開される文字列です。入力値が ``\\?\`` で始まると、展開は実行されません。

en: ``raw``: No conversions occur on the value passed in by Ansible
ja: ``raw``: Ansible によって渡される値で変換が行われません。

en: ``sid``: Will convert Windows security identifier values or Windows account names to a `SecurityIdentifier <https://docs.microsoft.com/en-us/dotnet/api/system.security.principal.securityidentifier?view=netframework-4.7.2>`_ value
ja: ``sid``: Windows セキュリティー識別子の値または Windows アカウント名を `SecurityIdentifier <https://docs.microsoft.com/en-us/dotnet/api/system.security.principal.securityidentifier?view=netframework-4.7.2>`_ 値に変換します。

en: ``str``: The value is converted to a string
ja: ``str``: この値は文字列に変換されます。

en: When ``type=dict``, or ``type=list`` and ``elements=dict``, the following keys can also be set for that module option:
ja: ``type=dict`` または ``type=list`` および ``elements=dict`` の場合は、そのモジュールオプションに以下のキーを設定することもできます。

en: ``apply_defaults``: The value is based on the ``options`` spec defaults for that key if ``True`` and null if ``False``. Only valid when the module option is not defined by the user and ``type=dict``.
ja: ``apply_defaults``: この値は、``True`` の場合はそのキーの ``options`` 仕様のデフォルトになり、``False`` の場合は null です。モジュールオプションがユーザーによって定義されておらず、``type=dict`` の場合に限り有効です。

en: ``mutually_exclusive``: Same as the root level ``mutually_exclusive`` but validated against the values in the sub dict
ja: ``mutually_exclusive``: ルートレベルの ``mutually_exclusive`` と同じですが、サブディクショナリーの値に対して検証されます。

en: ``options``: Same as the root level ``options`` but contains the valid options for the sub option
ja: ``options``: ルートレベルの ``options`` と同じですが、サブオプションの有効なオプションが含まれています。

en: ``required_if``: Same as the root level ``required_if`` but validated against the values in the sub dict
ja: ``required_if``: ルートレベルの ``required_if`` と同じですが、サブディクショナリーの値に対して検証されます。

en: ``required_by``: Same as the root level ``required_by`` but validated against the values in the sub dict
ja: ``required_by``: ルートレベルの ``required_by`` と同じですが、サブディクショナリーの値に対して検証されます。

en: ``required_together``: Same as the root level ``required_together`` but validated against the values in the sub dict
ja: ``required_together``: ルートレベルの ``required_together`` と同じですが、サブディクショナリーの値に対して検証されます。

en: ``required_one_of``: Same as the root level ``required_one_of`` but validated against the values in the sub dict
ja: ``required_one_of``: ルートレベルの ``required_one_of`` と同じですが、サブディクショナリーの値に対して検証されます。

en: A module type can also be a delegate function that converts the value to whatever is required by the module option. For example the following snippet shows how to create a custom type that creates a ``UInt64`` value:
ja: モジュール型は、値をモジュールオプションで必要とされるものに変換するデリゲート関数にすることもできます。次のスニペットの例は、``UInt64`` 値を作成するカスタム型を作成する方法を示しています。

en: When in doubt, look at some of the other core modules and see how things have been implemented there.
ja: 不明な場合は、他のコアモジュールを見て、そこにどのように実装されているかを見てみましょう。

en: Sometimes there are multiple ways that Windows offers to complete a task; this is the order to favor when writing modules:
ja: Windows がタスクを完了させるために、複数の方法が提示されることがあります。モジュールを書くときに好ましい順序は以下のようになります。

en: Native Powershell cmdlets like ``Remove-Item -Path C:\temp -Recurse``
ja: ``Remove-Item -Path C:\temp -Recurse`` などのネイティブの Powershell コマンドレッド

en: .NET classes like ``[System.IO.Path]::GetRandomFileName()``
ja: ``[System.IO.Path]::GetRandomFileName()`` などの .NET クラス

en: WMI objects through the ``New-CimInstance`` cmdlet
ja: ``New-CimInstance`` コマンドレッド経由の WMI オブジェクト

en: COM objects through ``New-Object -ComObject`` cmdlet
ja: ``New-Object -ComObject`` コマンドレッド経由の COM オブジェクト

en: Calls to native executables like ``Secedit.exe``
ja: ``Secedit.exe`` など、ネイティブ実行可能ファイルへの呼び出し

en: PowerShell modules support a small subset of the ``#Requires`` options built into PowerShell as well as some Ansible-specific requirements specified by ``#AnsibleRequires``. These statements can be placed at any point in the script, but are most commonly near the top. They are used to make it easier to state the requirements of the module without writing any of the checks. Each ``requires`` statement must be on its own line, but there can be multiple requires statements in one script.
ja: PowerShell モジュールは、PowerShell に組み込まれている ``#Requires`` オプションの小さなサブセットと、``#AnsibleRequires`` で指定されている Ansible 固有の要件をサポートしています。これらのステートメントは、スクリプトの任意の位置に配置できますが、最も一般的なのは先頭付近です。これらのステートメントは、チェック項目を記述することなく、モジュールの要件を簡単に記述するために使用されます。``requires`` ステートメントはそれぞれ 1 行に書かなければなりませんが、1 つのスクリプトに複数の requires ステートメントを記述することができます。

en: These are the checks that can be used within Ansible modules:
ja: 以下のチェックは、Ansible モジュール内で使用できます。

en: ``#Requires -Module Ansible.ModuleUtils.<module_util>``: Added in Ansible 2.4, specifies a module_util to load in for the module execution.
ja: ``#Requires -Module Ansible.ModuleUtils.<module_util>``: Ansible 2.4 で追加され、モジュール実行のために読み込むモジュールユーティリティーを指定します。

en: ``#Requires -Version x.y``: Added in Ansible 2.5, specifies the version of PowerShell that is required by the module. The module will fail if this requirement is not met.
ja: ``#Requires -Version x.y``: Ansible 2.5 で追加され、モジュールが必要とする PowerShell バージョンを指定します。この要件を満たしていない場合は失敗します。

en: ``#AnsibleRequires -OSVersion x.y``: Added in Ansible 2.5, specifies the OS build version that is required by the module and will fail if this requirement is not met. The actual OS version is derived from ``[Environment]::OSVersion.Version``.
ja: ``#AnsibleRequires -OSVersion x.y``: Ansible 2.5 で追加され、モジュールが必要とする OS ビルドバージョンを指定します。この要件を満たしていない場合は失敗します。実際の OS バージョンは ``[Environment]::OSVersion.Version`` から由来します。

en: ``#AnsibleRequires -Become``: Added in Ansible 2.5, forces the exec runner to run the module with ``become``, which is primarily used to bypass WinRM restrictions. If ``ansible_become_user`` is not specified then the ``SYSTEM`` account is used instead.
ja: ``#AnsibleRequires -Become``: Ansible 2.5 で追加され、exec ランナーが ``become`` でモジュールを強制的に実行します。これは主に WinRM の制限を回避するために使用されます。``ansible_become_user`` が指定されていない場合は、代わりに ``SYSTEM`` アカウントが使用されます。

en: ``#AnsibleRequires -CSharpUtil Ansible.<module_util>``: Added in Ansible 2.8, specifies a C# module_util to load in for the module execution.
ja: ``#AnsibleRequires -CSharpUtil Ansible.<module_util>``: Ansible 2.8 で追加され、モジュール実行のために読み込む C# モジュールユーティリティーを指定します。

en: C# module utils can reference other C# utils by adding the line ``using Ansible.<module_util>;`` to the top of the script with all the other using statements.
ja: C# モジュールユーティリティーは、すべてのステートメントを使用し、スクリプトの冒頭に ``using Ansible.<module_util>;`` 行を追加することで、他の C# ユーティリティーを参照できます。

en: Windows module utilities
ja: Windows モジュールユーティリティー

en: Like Python modules, PowerShell modules also provide a number of module utilities that provide helper functions within PowerShell. These module_utils can be imported by adding the following line to a PowerShell module:
ja: Python モジュールと同様に、PowerShell モジュールは、PowerShell でヘルパー関数を提供する多くのモジュールユーティリティーを提供します。これらのモジュールユーティリティーは、以下の行を PowerShell モジュールに追加してインポートできます。

en: This will import the module_util at ``./lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1`` and enable calling all of its functions. As of Ansible 2.8, Windows module utils can also be written in C# and stored at ``lib/ansible/module_utils/csharp``. These module_utils can be imported by adding the following line to a PowerShell module:
ja: これにより、モジュールユーティリティーが ``./lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1`` でインポートされ、すべての関数の呼び出しが可能になります。Ansible 2.8 と同様に、Windows モジュールユーティリティーは C# でも記述でき、``lib/ansible/module_utils/csharp`` に保存されます。これらのモジュールユーティリティーは、PowerShell モジュールに以下の行を追加することでインポートできます。

en: This will import the module_util at ``./lib/ansible/module_utils/csharp/Ansible.Basic.cs`` and automatically load the types in the executing process. C# module utils can reference each other and be loaded together by adding the following line to the using statements at the top of the util:
ja: これにより、``./lib/ansible/module_utils/csharp/Ansible.Basic.cs`` でモジュールユーティリティーがインポートされ、実行中のプロセスでタイプが自動的に読み込まれます。C# モジュールユーティリティーは相互に参照でき、次の行を、ユーティリティーの上部にある using ステートメントに追加して読み込むことができます。

en: There are special comments that can be set in a C# file for controlling the compilation parameters. The following comments can be added to the script;
ja: コンパイルパラメーターを制御するために C# ファイルに設定できる特別なコメントがあります。以下のコメントをスクリプトに追加できます。

en: ``//AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]``: The assembly DLL to reference during compilation, the optional ``-CLR`` flag can also be used to state whether to reference when running under .NET Core, Framework, or both (if omitted)
ja: ``//AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]``: コンパイル中に参照するアセンブリー DLL です。任意の ``-CLR`` フラグを使用して、.NET Core、Framework、またはその両方 (省略されている場合) で実行するときに参照するかどうかを表示することもできます。

en: ``//NoWarn -Name <error id> [-CLR [Core|Framework]]``: A compiler warning ID to ignore when compiling the code, the optional ``-CLR`` works the same as above. A list of warnings can be found at `Compiler errors <https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/index>`_
ja: ``//NoWarn -Name <error id> [-CLR [Core|Framework]]``: コードをコンパイルするときに無視するコンパイラ警告 ID で、任意の ``-CLR`` が上記と同じように機能します。警告のリストは、`コンパイラーエラー <https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/index>`_ で見つけることができます。

en: As well as this, the following pre-processor symbols are defined;
ja: この他に、以下のプリプロセッサーシンボルも定義されています。

en: ``CORECLR``: This symbol is present when PowerShell is running through .NET Core
ja: ``CORECLR``: このシンボルは、PowerShell が .NET Core を介して実行している場合に表示されます。

en: ``WINDOWS``: This symbol is present when PowerShell is running on Windows
ja: ``WINDOWS``: このシンボルは、PowerShell が Windows で実行している場合に表示されます。

en: ``UNIX``: This symbol is present when PowerShell is running on Unix
ja: ``UNIX``: このシンボルは、PowerShell が Unix で実行している場合に表示されます。

en: A combination of these flags help to make a module util interoperable on both .NET Framework and .NET Core, here is an example of them in action:
ja: これフラグの組み合わせは、.NET Framework と .NET Core の両方でモジュールユーティリティーを相互運用可能にするのに役立ちます。以下に、実際の動作例を示します。

en: The following is a list of module_utils that are packaged with Ansible and a general description of what they do:
ja: 以下に Ansible と一緒にパッケージ化されているモジュールユーティリティーのリストと、それらの機能の一般的な説明です。

en: ArgvParser: Utility used to convert a list of arguments to an escaped string compliant with the Windows argument parsing rules.
ja: ArgvParser: 引数のリストを Windows の引数解析ルールに準拠しているエスケープされた文字列に変換するのに使用されるユーティリティー。

en: CamelConversion: Utility used to convert camelCase strings/lists/dicts to snake_case.
ja: CamelConversion: camelCase strings/lists/dicts を snake_case に変換するのに使用されるユーティリティー。

en: CommandUtil: Utility used to execute a Windows process and return the stdout/stderr and rc as separate objects.
ja: CommandUtil: Windows プロセスを実行し、stdout/stderr と rc を異なるオブジェクトとして返すために使用されるユーティリティー。

en: FileUtil: Utility that expands on the ``Get-ChildItem`` and ``Test-Path`` to work with special files like ``C:\pagefile.sys``.
ja: FileUtil: ``C:\pagefile.sys`` のような特殊なファイルを扱うために ``Get-ChildItem`` および ``Test-Path`` を拡張するユーティリティー。

en: Legacy: General definitions and helper utilities for Ansible module.
ja: Legacy: Ansible モジュールの一般的な定義およびヘルパーユーティリティー。

en: LinkUtil: Utility to create, remove, and get information about symbolic links, junction points and hard inks.
ja: LinkUtil: シンボリックリンク、分岐点、ハードインクに関する情報を作成、削除、および取得するユーティリティー。

en: SID: Utilities used to convert a user or group to a Windows SID and vice versa.
ja: SID: ユーザーやグループを Windows SID に変換したり、Windows SID をユーザーやグループに変換するのに使用するユーティリティー。

en: For more details on any specific module utility and their requirements, please see the `Ansible module utilities source code <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils/powershell>`_.
ja: 特定のモジュールユーティリティーとその要件に関する詳細は、`Ansible モジュールユーティリティーのソースコード <https://github.com/ansible/ansible/tree/devel/lib/ansible/module_utils/powershell>`_ を参照してください。

en: PowerShell module utilities can be stored outside of the standard Ansible distribution for use with custom modules. Custom module_utils are placed in a folder called ``module_utils`` located in the root folder of the playbook or role directory.
ja: PowerShell モジュールユーティリティーは、カスタムモジュールで使用する標準の Ansible ディストリビューション外に保存できます。カスタムのモジュールユーティリティーは、Playbook またはロールディレクトリーのルートディレクトリーにある ``module_utils`` と呼ばれるディレクトリーに配置されます。

en: C# module utilities can also be stored outside of the standard Ansible distribution for use with custom modules. Like PowerShell utils, these are stored in a folder called ``module_utils`` and the filename must end in the extension ``.cs``, start with ``Ansible.``  and be named after the namespace defined in the util.
ja: C# モジュールユーティリティーは、カスタムモジュールで使用するための標準の Ansible ディストリビューション外にも保存できます。PowerShellutils と同様、``module_utils`` ディレクトリーに格納され、ファイル名は拡張子 ``.cs`` で終わり、``Ansible.`` で始まる、ユーティリティーで定義された名前空間の後に名前を指定する必要があります。

en: The below example is a role structure that contains two PowerShell custom module_utils called ``Ansible.ModuleUtils.ModuleUtil1``, ``Ansible.ModuleUtils.ModuleUtil2``, and a C# util containing the namespace ``Ansible.CustomUtil``::
ja: 次の例は、呼び出された 2 つの PowerShell のカスタムモジュールユーティリティー (``Ansible.ModuleUtils.ModuleUtil1``、``Ansible.ModuleUtils.ModuleUtil2``、および名前空間 ``Ansible.CustomUtil`` を含む C# ユーティリティー) を含むロール構造です。

en: Each PowerShell module_util must contain at least one function that has been exported with ``Export-ModuleMember`` at the end of the file. For example
ja: PowerShell の各モジュールユーティリティーには、ファイルの終わりに ``Export-ModuleMember`` でエクスポートされた関数が少なくとも 1 つ含まれている必要があります。以下に例を示します。

en: Exposing shared module options
ja: 共有モジュールオプションの公開

en: PowerShell module utils can easily expose common module options that a module can use when building its argument spec. This allows common features to be stored and maintained in one location and have those features used by multiple modules with minimal effort. Any new features or bugfixes added to one of these utils are then automatically used by the various modules that call that util.
ja: PowerShell モジュールユーティリティーは、引数仕様を構築する際にモジュールが使用できる共通のモジュールオプションを簡単に公開できます。これにより、共通の機能は 1 つの場所に保存および維持でき、最小限の作業で複数のモジュールによって使用される機能を利用できます。これらのユーティリティーのいずれかに追加された新機能またはバグ修正は、そのユーティリティーのいずれかを呼び出すさまざまなモジュールによって自動的に使用されます。

en: An example of this would be to have a module util that handles authentication and communication against an API This util can be used by multiple modules to expose a common set of module options like the API endpoint, username, password, timeout, cert validation, and so on without having to add those options to each module spec.
ja: この例としては、API に対する認証と通信を処理するモジュールユーティリティーがあります。このユーティリティーは、API エンドポイント、ユーザー名、パスワード、タイムアウト、認定検証などの共通のモジュールオプションセットを公開するため、各モジュール仕様にそれらのオプションを追加しなくても、複数のモジュールによって使用できます。

en: The standard convention for a module util that has a shared argument spec would have
ja: 共有引数仕様を持つモジュールユーティリティーの標準規則は次のようになります。

en: A ``Get-<namespace.name.util name>Spec`` function that outputs the common spec for a module
ja: モジュールの共通の仕様を出力する ``Get-<namespace.name.util name>Spec`` 関数

en: It is highly recommended to make this function name be unique to the module to avoid any conflicts with other utils that can be loaded
ja: 読み込みできる他のユーティリティーとの競合を避けるために、この関数名をモジュールに固有のものに強く推奨します。

en: The format of the output spec is a Hashtable in the same format as the ``$spec`` used for normal modules
ja: 出力仕様の形式は、通常のモジュールに使用される ``$spec`` と同じ形式のハッシュテーブルです。

en: A function that takes in an ``AnsibleModule`` object called under the ``-Module`` parameter which it can use to get the shared options
ja: ``-Module`` パラメーター下で呼び出された ``AnsibleModule`` オブジェクトを取り入れた関数。これを使用して共有オプションを取得できます。

en: Because these options can be shared across various module it is highly recommended to keep the module option names and aliases in the shared spec as specific as they can be. For example do not have a util option called ``password``, rather you should prefix it with a unique name like ``acme_password``.
ja: これらのオプションは各種モジュール間で共有できるため、モジュールオプション名とエイリアスを、可能な限り具体的な仕様に維持することが高く推奨されます。たとえば、``password`` ユーティリティーオプションがありません。たとえば、``acme_password`` などの一意の名前でプレフィックスを付けるべきではありません。

en: Failure to have a unique option name or alias can prevent the util being used by module that also use those names or aliases for its own options.
ja: 一意のオプション名またはエイリアスがないと、モジュールがユーティリティーを使用できなくなり、モジュールがそれらの名前またはエイリアスを独自のオプションに使用する可能性があります。

en: The following is an example module util called ``ServiceAuth.psm1`` in a collection that implements a common way for modules to authentication with a service.
ja: 以下は、コレクションで ``ServiceAuth.psm1`` モジュールユーティリティーの例になります。このモジュールは、サービスを使用した認証に共通の方法を実装します。

en: For a module to take advantage of this common argument spec it can be set out like
ja: モジュールがこの共通の引数仕様を利用できるようにするには、以下のように設定できます。

en: Options defined in the module spec will always have precedence over a util spec. Any list values under the same key in a util spec will be appended to the module spec for that same key. Dictionary values will add any keys that are missing from the module spec and merge any values that are lists or dictionaries. This is similar to how the doc fragment plugins work when extending module documentation.
ja: モジュール仕様に定義されているオプションは常にユーティリティー仕様よりも優先されます。ユーティリティー仕様の同じキー下のリスト値は、同じキーのモジュール仕様に追加されます。ディクショナリーの値は、モジュール仕様に不足している鍵を追加し、リストまたはディクショナリーである値をマージします。これは、モジュールドキュメントを拡張するときにドキュメントフラグメントプラグインがどのように機能するかと似ています。

en: To document these shared util options for a module, create a doc fragment plugin that documents the options implemented by the module util and extend the module docs for every module that implements the util to include that fragment in its docs.
ja: モジュールのこれらの共有ユーティリティーオプションを文書化するには、モジュールユーティリティーにより実装されたオプションを文書化するドキュメントフラグメントプラグインを作成し、ユーティリティーを実装するすべてのモジュールのモジュールドキュメントを拡張して、そのフラグメントをドキュメントに含めます。

en: Windows playbook module testing
ja: Windows Playbook モジュールのテスト

en: You can test a module with an Ansible playbook. For example:
ja: 以下のように、Ansible Playbook でモジュールをテストできます。以下に例を示します。

en: Create a playbook in any directory ``touch testmodule.yml``.
ja: 任意のディレクトリーに Playbook を作成します (``touch testmodule.yml``)。

en: Create an inventory file in the same directory ``touch hosts``.
ja: 同じディレクトリー ``touch hosts`` にインベントリーファイルを作成します。

en: Populate the inventory file with the variables required to connect to a Windows host(s).
ja: Windows ホストへの接続に必要な変数を指定してインベントリーファイルを設定します。

en: Run the playbook ``ansible-playbook -i hosts testmodule.yml``
ja: Playbook ``ansible-playbook -i hosts testmodule.yml`` を実行します。

en: This can be useful for seeing how Ansible runs with the new module end to end. Other possible ways to test the module are shown below.
ja: これは、Ansible が新しいモジュールでエンドツーエンドでどのように実行されるかを確認するのに役立ちます。モジュールをテストする他の可能な方法を以下に示します。

en: Windows debugging
ja: Windows のデバッグ

en: Debugging a module currently can only be done on a Windows host. This can be useful when developing a new module or implementing bug fixes. These are some steps that need to be followed to set this up:
ja: 現在、モジュールのデバッグは Windows ホストでのみ実行できます。これは、新しいモジュールを開発したり、バグ修正を実装したりするときに役立ちます。これを設定するには、次の手順に従う必要があります。

en: Copy the module script to the Windows server
ja: モジュールスクリプトを Windows サーバーにコピーします。

en: Copy the folders ``./lib/ansible/module_utils/powershell`` and ``./lib/ansible/module_utils/csharp`` to the same directory as the script above
ja: ``./lib/ansible/module_utils/powershell`` ディレクトリーと ``./lib/ansible/module_utils/csharp`` ディレクトリーを上記のスクリプトと同じディレクトリーにコピーします。

en: Add an extra ``#`` to the start of any ``#Requires -Module`` lines in the module code, this is only required for any lines starting with ``#Requires -Module``
ja: モジュールコードにあるすべての ``#Requires -Module`` 行の先頭に ``#`` を追加してください。これは、``#Requires -Module`` で始まる行にのみ必要です。

en: Add the following to the start of the module script that was copied to the server:
ja: 以下を、サーバーにコピーされたモジュールスクリプトの先頭に追加します。

en: You can add more args to ``$complex_args`` as required by the module or define the module options through a JSON file with the structure::
ja: モジュールに必要な場合は ``$complex_args`` にさらに引数を追加したり、その構造を持つ JSON ファイルでモジュールオプションを定義することもできます。

en: There are multiple IDEs that can be used to debug a Powershell script, two of the most popular ones are
ja: Powershell スクリプトのデバッグに使用できる IDE が複数あり、以下の 2 つが最も一般的なものになります。

en: To be able to view the arguments as passed by Ansible to the module follow these steps.
ja: Ansible がモジュールに渡した引数を表示するには、次の手順に従います。

en: Prefix the Ansible command with :envvar:`ANSIBLE_KEEP_REMOTE_FILES=1<ANSIBLE_KEEP_REMOTE_FILES>` to specify that Ansible should keep the exec files on the server.
ja: Ansible コマンドの前に :envvar:`ANSIBLE_KEEP_REMOTE_FILES=1<ANSIBLE_KEEP_REMOTE_FILES>` を付けて、Ansible が exec ファイルをサーバ上に保持するように指定します。

en: Log onto the Windows server using the same user account that Ansible used to execute the module.
ja: Ansible がモジュールの実行に使用したのと同じユーザーアカウントを使用して Windows サーバーにログインします。

en: Navigate to ``%TEMP%\..``. It should contain a folder starting with ``ansible-tmp-``.
ja: ``%TEMP%\..`` に移動します。これには、``ansible-tmp-`` で始まるディレクトリーが含まれるはずです。

en: Inside this folder, open the PowerShell script for the module.
ja: このディレクトリー内で、モジュールの PowerShell スクリプトを開きます。

en: In this script is a raw JSON script under ``$json_raw`` which contains the module arguments under ``module_args``. These args can be assigned manually to the ``$complex_args`` variable that is defined on your debug script or put in the ``args.json`` file.
ja: このスクリプトは、``$json_raw`` にある生の JSON スクリプトで、``module_args`` の下にモジュール引数が含まれています。これらの引数は、デバッグスクリプトで定義される ``$complex_args`` 変数に手動で割り当てたり、``args.json`` ファイルに置いたりできます。

en: Windows unit testing
ja: Windows ユニットテスト

en: Currently there is no mechanism to run unit tests for Powershell modules under Ansible CI.
ja: 現在、Ansible CI で Powershell モジュールのユニットテストを実行するメカニズムはありません。

en: Windows integration testing
ja: Windows 統合テスト

en: Integration tests for Ansible modules are typically written as Ansible roles. These test roles are located in ``./test/integration/targets``. You must first set up your testing environment, and configure a test inventory for Ansible to connect to.
ja: Ansible モジュールの統合テストは通常 Ansible ロールとして記述されます。これらのテストロールは ``./test/integration/targets`` にあります。まず、テスト環境を設定して、Ansible が接続できるようにテストインベントリーを設定する必要があります。

en: In this example we will set up a test inventory to connect to two hosts and run the integration tests for win_stat:
ja: この例では、2 つのホストに接続し、win_stat の統合テストを実行するためのテストインベントリーを設定します。

en: Run the command ``source ./hacking/env-setup`` to prepare environment.
ja: 環境を準備するには、``source ./hacking/env-setup`` コマンドを実行します。

en: Create a copy of ``./test/integration/inventory.winrm.template`` and name it ``inventory.winrm``.
ja: ``./test/integration/inventory.winrm.template`` のコピーを作成し、``inventory.winrm`` という名前を指定します。

en: Fill in entries under ``[windows]`` and set the required variables that are needed to connect to the host.
ja: ``[windows]`` の下にエントリーを入力し、ホストへの接続に必要な変数を設定します。

en: :ref:`Install the required Python modules <windows_winrm>` to support WinRM and a configured authentication method.
ja: WinRM と、設定された認証方法をサポートするのに :ref:`必要な Python モジュールをインストール <windows_winrm>` します。

en: To execute the integration tests, run ``ansible-test windows-integration win_stat``; you can replace ``win_stat`` with the role you want to test.
ja: 統合テストを実行するには、``ansible-test windows-integration win_stat`` を実行します。``win_stat`` は、テストするロールに置き換えることができます。

en: This will execute all the tests currently defined for that role. You can set the verbosity level using the ``-v`` argument just as you would with ansible-playbook.
ja: これにより、そのロールに対して現在定義されているすべてのテストが実行されます。ansible-playbook の場合と同じように、``-v`` 引数を使用して詳細レベルを設定できます。

en: When developing tests for a new module, it is recommended to test a scenario once in check mode and twice not in check mode. This ensures that check mode does not make any changes but reports a change, as well as that the second run is idempotent and does not report changes. For example:
ja: 新しいモジュールのテストを開発するときは、シナリオをチェックモードで 1 回、チェックモード以外で 2 回テストすることが推奨されます。これにより、チェックモードでは変更は行われず、変更が報告されます。また、2 回目の実行はべき等であり、変更は報告されません。以下に例を示します。

en: Windows communication and development support
ja: Windows の通信および開発サポート

en: Join the ``#ansible-devel`` or ``#ansible-windows`` irc channels on `irc.libera.chat <https://libera.chat/>`_ for discussions about Ansible development for Windows.
ja: `irc.libera.chat <https://libera.chat/>`_ の IRC チャンネル ``#ansible-devel`` または ``#ansible-windows`` に参加し、Windows 用 の Ansible 開発に関する議論を行うこと。

en: Creating a new collection
ja: 新規コレクションの作成

en: Starting with Ansible 2.10, related modules should be developed in a collection. The Ansible core team and community compiled these module development tips and tricks to help companies developing Ansible modules for their products and users developing Ansible modules for third-party products. See :ref:`developing_collections` for a more detailed description of the collections format and additional development guidelines.
ja: Ansible 2.10 以降、関連するモジュールをコレクションで開発する必要があります。Ansible コアチームおよびコミュニティーは、これらのモジュール開発のヒントとコツをまとめて、自社製品用の Ansible モジュールを開発している企業や、サードパーティー製品用の Ansible モジュールを開発しているユーザーを支援します。コレクションの形式と追加の開発ガイドラインの詳細は、「:ref:`developing_collections`」を参照してください。

en: Before you start coding
ja: コーディングを開始する前に

en: This list of prerequisites is designed to help ensure that you develop high-quality modules that work well with ansible-core and provide a seamless user experience.
ja: この前提条件のリストは、ansible-core で適切に機能し、シームレスなユーザーエクスペリエンスを提供する高品質のモジュールを確実に開発できるように設計されています。

en: Read though all the pages linked off :ref:`developing_modules_general`; paying particular focus to the :ref:`developing_modules_checklist`.
ja: 「:ref:`developing_modules_general`」からリンクされているすべてのページを読み込みます。特に、「:ref:`developing_modules_checklist`」に注意してください。

en: We encourage PEP 8 compliance. See :ref:`testing_pep8` for more information.
ja: PEP 8 コンプライアンスが推奨されます。詳細は「:ref:`testing_pep8`」を参照してください。

en: We encourage supporting :ref:`Python 2.6+ and Python 3.5+ <developing_python_3>`.
ja: :ref:`Python 2.6+ and Python 3.5+ <developing_python_3>` をサポートすることが推奨されます。

en: Look at Ansible Galaxy and review the naming conventions in your functional area (such as cloud, networking, databases).
ja: Ansible Galaxy を確認し、機能エリア (クラウド、ネットワーク、データベースなど) で命名規則を確認します。

en: With great power comes great responsibility: Ansible collection maintainers have a duty to help keep content up to date and release collections they are responsible for regularly. As with all successful community projects, collection maintainers should keep a watchful eye for reported issues and contributions.
ja: 大きな力には大きな責任が伴います。Ansible コレクションのメンテナーには、コンテンツを最新の状態に保ち、定期的に責任のあるコレクションをリリースするのを支援する義務があります。成功しているすべてのコミュニティープロジェクトと同様に、コレクションのメンテナーは、報告された問題や貢献に注意を払う必要があります。

en: We strongly recommend unit and/or integration tests. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
ja: ユニットテストや統合テストが強く推奨されます。ユニットテストは、外部リソース (クラウドやネットワークデバイスなど) が必要な場合に特に役に立ちます。詳細については、「:ref:`developing_testing`」および「`ワーキンググループのテスト <https://github.com/ansible/community/blob/master/meetings/README.md>`_」を参照してください。

en: Naming conventions
ja: 命名規則

en: Fully Qualified Collection Names (FQCNs) for plugins and modules include three elements:
ja: プラグインおよびモジュール用の完全修飾コレクション名 (FQCN) には 3 つの要素があります。

en: the Galaxy namespace, which generally represents the company or group
ja: Galaxy 名前空間。通常、会社またはグループを表します。

en: the collection name, which generally represents the product or OS
ja: コレクション名。通常は製品または OS を表します。

en: the plugin or module name
ja: プラグインまたはモジュール名

en: always in lower case
ja: 常に小文字

en: words separated with an underscore (``_``) character
ja: 単語はアンダースコア (``_``) 文字で区切られます。

en: singular, rather than plural, for example, ``command`` not ``commands``
ja: 複数形ではなく、単数形 (例: ``commands`` ではなく ``command``)

en: For example, ``community.mongodb.mongodb_linux`` or ``cisco.meraki.meraki_device``.
ja: たとえば、``community.mongodb.mongodb_linux`` または ``cisco.meraki.meraki_device`` です。

en: It is convenient if the organization and repository names on GitHub (or elsewhere) match your namespace and collection names on Ansible Galaxy, but it is not required. The plugin names you select, however, are always the same in your code repository and in your collection artifact on Galaxy.
ja: GitHub (または別の場所) の組織とリポジトリー名が Ansible Galaxy の名前空間とコレクション名と一致する場合に便利ですが、必須ではありません。ただし、選択したプラグイン名は、コードリポジトリーと Galaxy のコレクションアーティファクトで常に同じです。

en: Speak to us
ja: お問い合わせ

en: Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the "Before you start coding" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use.
ja: コーディングの前にアイデアを出し合うことで、良い習慣を取り入れ、よくある間違いを避けることができます。「コーディングを始める前に」のセクションを読んだ後、モジュールの構造について妥当なアイデアがあるはずです。提案するプラグインやモジュールの名前のリストを書き、それぞれが何をするのかを簡単に説明してください。そのリストを、IRC やメーリングリストで共有して、Ansible コミュニティーが一貫性や親しみやすさの観点からアイデアを検討できるようにします。一貫性があり、予測可能で、親しみやすい名前や機能は、コレクションをより使いやすくします。

en: Where to get support
ja: サポートを受ける場所

en: Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
ja: Ansible には、活発で知識が豊富なモジュール開発者のコミュニティーがあり、質問に答えるための素晴らしいリソースとなっています。

en: In the :ref:`ansible_community_guide` you can find how to:
ja: :ref:`ansible_community_guide` で、以下の方法を見つけることができます。

en: Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list"
ja: メーリングリストをサブスクライブすること。「Ansible Development List」および「Ansible Announce list」をお勧めします。

en: ``#ansible-devel`` - We have found that communicating on the IRC channel, ``#ansible-devel`` on `libera.chat's <https://libera.chat/>`_ IRC network works best for developers so we can have an interactive dialogue.
ja: ``#ansible-devel`` - `libera.chat's <https://libera.chat/>`_ の IRC ネットワーク ``#ansible-devel`` では、インタラクティブな対話を行うことができるため、開発者に最適なものであることが分かっています。

en: IRC meetings - Join the various weekly IRC meetings `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
ja: IRC ミーティング。様々な IRC ミーティング (毎週) に参加してください。「`ミーティングスケジュールおよび議題のページ <https://github.com/ansible/community/blob/master/meetings/README.md>`_」を参照してください。

en: Required files
ja: 必須ファイル

en: Your collection should include the following files to be usable:
ja: コレクションには、使用可能な以下のファイルが含まれているはずです。

en: an ``__init__.py`` file - An empty file to initialize namespace and allow Python to import the files. *Required*
ja: ``__init__.py`` ファイル - 名前空間を初期化し、Python がファイルをインポートできるようにする空のファイル。*必須*

en: at least one plugin, for example, ``/plugins/modules/$your_first_module.py``. *Required*
ja: 少なくとも 1 つのプラグイン (例: ``/plugins/modules/$your_first_module.py``)。*必須*

en: if needed, one or more ``/plugins/doc_fragments/$topic.py`` files - Code documentation, such as details regarding common arguments. *Optional*
ja: 必要な場合は、1 つ以上の ``/plugins/doc_fragments/$topic.py`` ファイル - 一般的な引数の詳細などのコードのドキュメント。*任意*

en: if needed, one or more ``/plugins/module_utils/$topic.py`` files - Code shared between more than one module, such as common arguments. *Optional*
ja: 必要な場合は、1 つ以上の ``/plugins/module_utils/$topic.py`` ファイル - 一般的な引数などの、複数のモジュール間で共有されるコード。*任意*

en: When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection.
ja: これらのファイルの準備が整ったら、:ref:`developing_modules_checklist` を再度確認します。新しいコレクションを作成する場合は、貢献のルール設定、レビュー担当者の見つけ方、コレクションにおけるコードのテストおよび保守など、リポジトリーに関連するすべての手順を担当します。

en: If you need help or advice, consider joining the ``#ansible-devel`` IRC channel (see how in the :ref:`Where to get support <developing_in_groups_support>` section).
ja: さらにヘルプまたはアドバイスが必要な場合は、IRC チャンネル ``#ansible-devel`` に参加することを検討してください (「:ref:`サポートを得る方法 <developing_in_groups_support>`」を参照してください)。

en: New to git or GitHub
ja: git または GitHub をはじめて使用する場合

en: We realize this may be your first use of Git or GitHub. The following guides may be of use:
ja: ここでは、Git または GitHub を初めて使用するユーザーを対象としています。次のガイドが参考になるかもしれません。

en: Developing plugins
ja: プラグインの開発

en: Plugins augment Ansible's core functionality with logic and features that are accessible to all modules. Ansible collections include a number of handy plugins, and you can easily write your own. All plugins must:
ja: プラグインは、すべてのモジュールがアクセスできるロジックおよび機能を使用して Ansible のコア機能を拡張します。Ansible コレクションには多くの便利なプラグインが含まれており、独自のプラグインを簡単に作成できます。すべてのプラグインでは、以下を行う必要があります。

en: be written in Python
ja: Python で書かれている。

en: raise errors
ja: エラーを発生させる。

en: return strings in unicode
ja: Unicode で文字列を返す。

en: conform to Ansible's configuration and documentation standards
ja: Ansible の設定およびドキュメントの標準仕様に準拠する。

en: Once you've reviewed these general guidelines, you can skip to the particular type of plugin you want to develop.
ja: これらの一般的なガイドラインを確認したら、開発する特定のタイプのプラグインに進んでください。

en: Writing plugins in Python
ja: Python でのプラグインの作成

en: You must write your plugin in Python so it can be loaded by the ``PluginLoader`` and returned as a Python object that any module can use. Since your plugin will execute on the controller, you must write it in a :ref:`compatible version of Python <control_node_requirements>`.
ja: ``PluginLoader`` により読み込まれ、モジュールが使用できる Python オブジェクトとして返すには、Python でプラグインを作成する必要があります。プラグインはコントローラーで実行するため、:ref:`互換性のある Python バージョン <control_node_requirements>` で作成する必要があります。

en: Raising errors
ja: エラーの発生

en: You should return errors encountered during plugin execution by raising ``AnsibleError()`` or a similar class with a message describing the error. When wrapping other exceptions into error messages, you should always use the ``to_native`` Ansible function to ensure proper string compatibility across Python versions:
ja: プラグインの実行中に発生したエラーは、``AnsibleError()`` またはエラーを記述したメッセージのある同様のクラスを発生させて返す必要があります。他の例外をエラーメッセージにラップする場合は、Python のバージョン間で適切な文字列の互換性を確保するために、常に Ansible 関数の ``to_native`` を使用する必要があります。

en: Check the different `AnsibleError objects <https://github.com/ansible/ansible/blob/devel/lib/ansible/errors/__init__.py>`_ and see which one applies best to your situation.
ja: さまざまな `AnsibleError オブジェクト <https://github.com/ansible/ansible/blob/devel/lib/ansible/errors/__init__.py>`_ を確認して、お使いの状況に最適なものを確認します。

en: String encoding
ja: 文字列エンコーディング

en: You must convert any strings returned by your plugin into Python's unicode type. Converting to unicode ensures that these strings can run through Jinja2. To convert strings:
ja: プラグインによって返される文字列は、Python の Unicode タイプに変換する必要があります。Unicode に変換すると、これらの文字列が Jinja2 を介して実行できるようになります。文字列を変換するには、次を実行します。

en: Plugin configuration & documentation standards
ja: プラグインの設定およびドキュメントの標準仕様

en: To define configurable options for your plugin, describe them in the ``DOCUMENTATION`` section of the python file. Callback and connection plugins have declared configuration requirements this way since Ansible version 2.4; most plugin types now do the same. This approach ensures that the documentation of your plugin's options will always be correct and up-to-date. To add a configurable option to your plugin, define it in this format:
ja: プラグインの設定可能なオプションを定義するには、python ファイルの ``DOCUMENTATION`` セクションに記述します。コールバックおよび接続プラグインは、Ansible バージョン 2.4 以降、この方法で設定要件を宣言します。現在、ほとんどのプラグインタイプが同じように動作するようになりました。この方法により、プラグインのオプションのドキュメントが常に正確で最新の状態になります。設定可能なオプションをプラグインに追加するには、以下の形式で定義します。

en: To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``. For most plugin types, the controller pre-populates the settings. If you need to populate settings explicitly, use a ``self.set_options()`` call.
ja: プラグインの設定にアクセスするには、``self.get_option(<option_name>)`` を使用します。ほとんどのプラグインタイプでは、コントローラーは設定を事前に設定します。設定を明示的に設定する必要がある場合は、``self.set_options()`` 呼び出しを使用します。

en: Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should include well-formed doc strings. If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy. See :ref:`module_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use.
ja: 埋め込みドキュメントをサポートするプラグイン (:ref:`ansible-doc` リストの場合を参照) は、適切に構築されたドキュメント文字列を含める必要があります。プラグインから継承する場合は、ドキュメントフラグメントを介して、またはコピーとして、必要なオプションを記述する必要があります。正しいドキュメントに関する詳細は、「:ref:`module_documenting`」を参照してください。ローカルで使用するプラグインを開発している場合でも、完全なドキュメントを作成することが推奨されます。

en: Developing particular plugin types
ja: 特定のプラグインタイプの開発

en: Action plugins
ja: action プラグイン

en: Action plugins let you integrate local processing and local data with module functionality.
ja: action プラグインを使用すると、ローカル処理とローカルデータをモジュール機能に統合できます。

en: To create an action plugin, create a new class with the Base(ActionBase) class as the parent:
ja: action プラグインを作成するには、Base(ActionBase) クラスを親として新しいクラスを作成します。

en: From there, execute the module using the ``_execute_module`` method to call the original module. After successful execution of the module, you can modify the module return data.
ja: そこから、``_execute_module`` メソッドを使用してモジュールを実行して、元のモジュールを呼び出します。モジュールの実行に成功すると、モジュールの戻り値データを変更できます。

en: For example, if you wanted to check the time difference between your Ansible controller and your target machine(s), you could write an action plugin to check the local time and compare it to the return data from Ansible's ``setup`` module:
ja: たとえば、Ansible コントローラーとターゲットマシン間の時間差を確認する場合は、action プラグインを作成してローカルタイムを確認し、それを Ansible の ``setup`` モジュールから返されるデータと比較できます。

en: This code checks the time on the controller, captures the date and time for the remote machine using the ``setup`` module, and calculates the difference between the captured time and the local time, returning the time delta in days, seconds and microseconds.
ja: このコードはコントローラーの時間を確認し、``setup`` モジュールを使用してリモートマシンの日時を取得し、取得した時間とローカル時間の差異を算出し、その時間差を日数、秒、およびマイクロ秒で返します。

en: For practical examples of action plugins, see the source code for the `action plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/action>`_
ja: action プラグインの実際の例は、`Ansible Core に同梱される action プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/action>`_ のソースコードを参照してください。

en: Cache plugins
ja: Cache プラグイン

en: Cache plugins store gathered facts and data retrieved by inventory plugins.
ja: Cache プラグインは、Inventory プラグインによって取得されるファクトおよびデータを収集したデータを格納します。

en: Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self.get_option(<option_name>)``. If you import a cache plugin directly in the code base, you can only access options via ``ansible.constants``, and you break the cache plugin's ability to be used by an inventory plugin.
ja: ``self.set_options()`` および ``self.get_option(<option_name>)`` を使用できる cache_loader を使用する cache プラグインをインポートします。コードベースで cache プラグインを直接インポートする場合は、``ansible.constants`` からのみオプションにアクセスでき、inventory プラグインによって使用される cache プラグインの機能が壊れます。

en: There are two base classes for cache plugins, ``BaseCacheModule`` for database-backed caches, and ``BaseCacheFileModule`` for file-backed caches.
ja: cache プラグインには、2 つのベースクラス (データベースベースのバックアップ用のキャッシュの場合は ``BaseCacheModule``、ファイルのバックアップ用のキャッシュの場合は ``BaseCacheFileModule``) があります。

en: To create a cache plugin, start by creating a new ``CacheModule`` class with the appropriate base class. If you're creating a plugin using an ``__init__`` method you should initialize the base class with any provided args and kwargs to be compatible with inventory plugin cache options. The base class calls ``self.set_options(direct=kwargs)``. After the base class ``__init__`` method is called ``self.get_option(<option_name>)`` should be used to access cache options.
ja: キャッシュプラグインを作成するには、適切なベースクラスで新しい ``CacheModule`` クラスを作成して開始します。``__init__`` メソッドを使用してプラグインを作成する場合は、指定された arg および kwarg でベースクラスを初期化し、インベントリープラグインキャッシュオプションと互換性がある必要があります。ベースクラスは ``self.set_options(direct=kwargs)`` を呼び出します。ベースクラス ``__init__`` メソッドが呼び出されると、``self.get_option(<option_name>)`` を使用して、キャッシュオプションにアクセスする必要があります。

en: New cache plugins should take the options ``_uri``, ``_prefix``, and ``_timeout`` to be consistent with existing cache plugins.
ja: 新しい cache プラグインは、既存の cache プラグインとの整合性を保つために、``_uri`` オプション、``_prefix`` オプション、および ``_timeout`` オプションを使用する必要があります。

en: If you use the ``BaseCacheModule``, you must implement the methods ``get``, ``contains``, ``keys``, ``set``, ``delete``, ``flush``, and ``copy``. The ``contains`` method should return a boolean that indicates if the key exists and has not expired. Unlike file-based caches, the ``get`` method does not raise a KeyError if the cache has expired.
ja: ``BaseCacheModule`` を使用する場合は、メソッド ``get``、``contains``、``keys``、``set``、``delete``、``flush``、および ``copy`` を実装する必要があります。``contains`` メソッドは、キーが存在し、有効期限が切れていないことを示すブール値を返すはずです。ファイルベースのキャッシュとは異なり、キャッシュの有効期限が切れると、``get`` メソッドによって KeyError は発生しません。

en: If you use the ``BaseFileCacheModule``, you must implement ``_load`` and ``_dump`` methods that will be called from the base class methods ``get`` and ``set``.
ja: ``BaseFileCacheModule`` を使用する場合は、ベースクラスメソッド ``get`` および ``set`` から呼び出される ``_load`` メソッドおよび ``_dump`` メソッドを実装する必要があります。

en: If your cache plugin stores JSON, use ``AnsibleJSONEncoder`` in the ``_dump`` or ``set`` method  and ``AnsibleJSONDecoder`` in the ``_load`` or ``get`` method.
ja: キャッシュプラグインに JSON が保存されている場合は、``_dump`` メソッドまたは ``set`` メソッドの ``AnsibleJSONEncoder`` と、``_load`` メソッドまたは``get`` メソッドの ``AnsibleJSONDecoder`` を使用します。

en: For example cache plugins, see the source code for the `cache plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/cache>`_.
ja: cache プラグインの例は、`Ansible Core に同梱される cache プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/cache>`_ のソースコードを参照してください。

en: Callback plugins
ja: callback プラグイン

en: Callback plugins add new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs.
ja: callback プラグインは、イベントに応答する際に新しい動作を Ansible に追加します。デフォルトでは、callback プラグインは、コマンドラインプログラムの実行時に表示されるほとんどの出力を制御します。

en: To create a callback plugin, create a new class with the Base(Callbacks) class as the parent:
ja: callback プラグインを作成するには、Base(Callbacks) クラスを親として使用して新規クラスを作成します。

en: From there, override the specific methods from the CallbackBase that you want to provide a callback for. For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with ``v2``. For a complete list of methods that you can override, please see ``__init__.py`` in the `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
ja: そこから、コールバックを提供する CallbackBase から特定のメソッドを上書きします。Ansible バージョン 2.0 以降で使用するプラグインでは、``v2`` で始まる方法のみを上書きしてください。上書きできるメソッドの完全なリストは、`lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ ディレクトリーの ``__init__.py`` を参照してください。

en: The following is a modified example of how Ansible's timer plugin is implemented, but with an extra option so you can see how configuration works in Ansible version 2.4 and later:
ja: 以下は、Ansible の timer プラグインの実装方法の変更例です。ただし、追加のオプションを使用すると、Ansible バージョン 2.4 以降で構成がどのように機能するかを確認できます。

en: Note that the ``CALLBACK_VERSION`` and ``CALLBACK_NAME`` definitions are required for properly functioning plugins for Ansible version 2.0 and later. ``CALLBACK_TYPE`` is mostly needed to distinguish 'stdout' plugins from the rest, since you can only load one plugin that writes to stdout.
ja: ``CALLBACK_VERSION`` および ``CALLBACK_NAME`` の定義は、Ansible バージョン 2.0 以降のプラグインが正しく機能するために必要であることに注意してください。``CALLBACK_TYPE`` は、標準出力 (stdout) に書き込むプラグインを 1 つだけ読み込むことができるため、ほとんどの「stdout」プラグインをその他のものと区別するために必要です。

en: For example callback plugins, see the source code for the `callback plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_
ja: callback プラグインの例は、`Ansible Core に同梱される callback プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ のソースコードを参照してください。

en: New in ansible-core 2.11, callback plugins are notified (via ``v2_playbook_on_task_start``) of :ref:`meta<meta_module>` tasks. By default, only explicit ``meta`` tasks that users list in their plays are sent to callbacks.
ja: ansible-core 2.11 の新機能として、:ref:`meta<meta_module>` タスクのコールバックプラグインが (``v2_playbook_on_task_start`` を介して) 通知されます。デフォルトでは、プレイに追加する明示的な ``meta`` タスクのみが、コールバックに送信されます。

en: There are also some tasks which are generated internally and implicitly at various points in execution. Callback plugins can opt-in to receiving these implicit tasks as well, by setting ``self.wants_implicit_tasks = True``. Any ``Task`` object received by a callback hook will have an ``.implicit`` attribute, which can be consulted to determine whether the ``Task`` originated from within Ansible, or explicitly by the user.
ja: 実行のさまざまな時点で、内部的および暗黙的に生成されるタスクもいくつかあります。callback プラグインは、``self.wants_implicit_tasks = True`` を設定することにより、これらの暗黙的なタスクを受け取ることをオプトインできます。コールバックフックによって受信された ``Task`` オブジェクトには、``.implicit`` 属性があります。これを参照して、``Task`` が Ansible 内から、またはユーザーによって明示的に発信されたかどうかを決めるために参照します。

en: Connection plugins
ja: connection プラグイン

en: Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are the ``paramiko`` SSH, native ssh (just called ``ssh``), and ``local`` connection types.  All of these can be used in playbooks and with ``/usr/bin/ansible`` to connect to remote machines.
ja: connection プラグインにより、Ansible はターゲットホストに接続してそのホストにあるタスクを実行できるようにします。Ansible には多くの接続プラグインが同梱されていますが、一度に使用できるのは 1 つのみとなります。最も一般的に使用される接続プラグインは、``paramiko`` SSH、ネイティブ ssh (単に ``ssh`` と呼ばれる)、および ``local`` 接続タイプです。これらはすべて Playbook で使用され、``/usr/bin/ansible`` を使用してリモートマシンに接続します。

en: Ansible version 2.1 introduced the ``smart`` connection plugin. The ``smart`` connection type allows Ansible to automatically select either the ``paramiko`` or ``openssh`` connection plugin based on system capabilities, or the ``ssh`` connection plugin if OpenSSH supports ControlPersist.
ja: Ansible バージョン 2.1 では、``smart`` 接続プラグインが導入されます。``smart`` 接続タイプにより、Ansible は、システム機能に基づいて、``paramiko`` 接続プラグインまたは ``openssh`` 接続プラグインのいずれかを自動的に選択できますが、OpenSSH が ControlPersist に対応している場合は connetion プラグイン ``ssh`` を選択します。

en: To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into ``connection`` directory on your :ref:`local plugin path <local_plugins>`.
ja: 新しい connetion プラグイン (SNMP、メッセージバス、またはその他のトランスポートをサポートする場合など) を作成するには、既存の connetion プラグインのいずれかの形式をコピーして、:ref:`ローカルプラグインパス <local_plugins>` にある ``connection`` ディレクトリーに置きます。

en: Connection plugins can support common options (such as the ``--timeout`` flag) by defining an entry in the documentation for the attribute name (in this case ``timeout``). If the common option has a non-null default, the plugin should define the same default since a different default would be ignored.
ja: 接続プラグインは、属性名 (ここでは ``timeout``) のドキュメントでエントリーを定義することで、一般的なオプション (``--timeout`` フラグなど) をサポートします。一般的なオプションには null 以外のデフォルトがある場合、別のデフォルトは無視されるため、プラグインは同じデフォルトを定義する必要があります。

en: For example connection plugins, see the source code for the `connection plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_.
ja: 選択プラグインの例は、`Ansible Core に同梱される接続プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_ のソースコードを参照してください。

en: Filter plugins
ja: filter プラグイン

en: Filter plugins manipulate data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the filter plugins shipped with Ansible reside in a ``core.py``.
ja: filter プラグインはデータを操作します。これらは Jinja2 の機能であり、``template`` モジュールが使用する Jinja2 テンプレートで利用できます。すべてのプラグインと同様に、プラグインは簡単に拡張できますが、プラグインごとにファイルを作成する代わりに、ファイルごとに複数のプラグインを作成できます。Ansible に同梱されているフィルタープラグインのほとんどは、``core.py`` にあります。

en: Filter plugins do not use the standard configuration and documentation system described above.
ja: filter プラグインは、上記の標準設定およびドキュメントシステムを使用しません。

en: For example filter plugins, see the source code for the `filter plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_.
ja: filter プラグインの例は、`Ansible Core に同梱される filter プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_ のソースコードを参照してください。

en: Inventory plugins parse inventory sources and form an in-memory representation of the inventory. Inventory plugins were added in Ansible version 2.4.
ja: inventory プラグインはインベントリーソースを解析し、インベントリーのインメモリー表示を形成します。inventory プラグインは Ansible バージョン 2.4 で追加されました。

en: You can see the details for inventory plugins in the :ref:`developing_inventory` page.
ja: inventory プラグインの詳細は、:ref:`developing_inventory` ページを参照してください。

en: Lookup plugins
ja: lookup プラグイン

en: Lookup plugins pull in data from external data stores. Lookup plugins can be used within playbooks both for looping --- playbook language constructs like ``with_fileglob`` and ``with_items`` are implemented via lookup plugins --- and to return values into a variable or parameter.
ja: lookup プラグインは、外部データストアからデータをプルします。lookup プラグインは Playbook 内でループするため (``with_fileglob`` や ``with_items`` などの Playbook 言語の構造は lookup プラグインを介して実装されています)、また変数やパラメーターに値を返すために使用することができます。

en: Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When writing lookup plugins, always return data of a consistent type that can be easily consumed in a playbook. Avoid parameters that change the returned data type. If there is a need to return a single value sometimes and a complex dictionary other times, write two different lookup plugins.
ja: lookup プラグインは非常に柔軟性があるため、あらゆるタイプのデータを取得し、返すことができます。lookup プラグインを記述する際には、Playbook で簡単に使用できる一貫性のあるタイプのデータを常に返します。返されたデータ型を変更するパラメーターは使用しないでください。単一の値を返さなければならないときもあれば、複雑なディクショナリーを返さなければない場合もあります。この場合は、lookup プラグインを 2 つ記述してください。

en: Ansible includes many :ref:`filters <playbooks_filters>` which can be used to manipulate the data returned by a lookup plugin. Sometimes it makes sense to do the filtering inside the lookup plugin, other times it is better to return results that can be filtered in the playbook. Keep in mind how the data will be referenced when determining the appropriate level of filtering to be done inside the lookup plugin.
ja: Ansible には、lookup プラグインが返すデータを操作するために使用できる :ref:`filters <playbooks_filters>` が多数含まれています。lookup プラグイン内でフィルタリングを行うことが理にかなっている場合もあれば、Playbook でフィルタリングできる結果を返す方がよい場合もあります。lookup プラグイン内で実行する適切なフィルタリングレベルを決定するときは、データがどのように参照されるかに留意してください。

en: Here's a simple lookup plugin implementation --- this lookup returns the contents of a text file as a variable:
ja: 以下は簡単な lookup プラグインの実装です。この lookup は、テキストファイルの内容を変数として返します。

en: The following is an example of how this lookup is called:
ja: 以下は、このルックアップがどのように呼び出されるかの例になります。

en: For example lookup plugins, see the source code for the `lookup plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
ja: lookup プラグインの例は、`Ansible Core に同梱される lookup プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_ のソースコードを参照してください。

en: For more usage examples of lookup plugins, see :ref:`Using Lookups<playbooks_lookups>`.
ja: lookup プラグインのその他の使用例については、「:ref:`検索の使用<playbooks_lookups>`」を参照してください。

en: Test plugins
ja: test プラグイン

en: Test plugins verify data. They are a feature of Jinja2 and are also available in Jinja2 templates used by the ``template`` module. As with all plugins, they can be easily extended, but instead of having a file for each one you can have several per file. Most of the test plugins shipped with Ansible reside in a ``core.py``. These are specially useful in conjunction with some filter plugins like ``map`` and ``select``; they are also available for conditional directives like ``when:``.
ja: テストプラグインはデータを検証します。これは Jinja2 の機能で、``template`` モジュールが使用する Jinja2 テンプレートでも利用できます。他のすべてのプラグインと同様、このプラグインは簡単に拡張できますが、プラグインごとにファイルを作成する代わりに、ファイルごとに複数のプラグインを作成できます。Ansible に同梱されているテストプラグインのほとんどは、``core.py`` に格納されています。これらのプラグインは、``map`` や ``select`` などの filter プラグインと組み合わせて使うと特に便利です。また、``when:`` などの条件付きディレクティブにも利用できます。

en: Test plugins do not use the standard configuration and documentation system described above.
ja: test プラグインは、上記の標準設定およびドキュメントシステムを使用しません。

en: For example test plugins, see the source code for the `test plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/test>`_.
ja: test プラグインの例は、`Ansible Core に同梱される test プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/test>`_ のソースコードを参照してください。

en: Vars plugins
ja: vars プラグイン

en: Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins.
ja: vars プラグインは、インベントリーソース、Playbook、またはコマンドラインに組み込まれていない Ansible の実行に、変数データを追加します。「host_vars」や「group_vars」のような Playbook の構成要素は、vars プラグインを使用します。

en: Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. Vars plugins are unsupported by collections.
ja: vars プラグインは Ansible 2.0 に部分的に実装され、Ansible 2.4 以降では、完全実装になるように書き直されました。vars プラグインはコレクションのサポート対象外となります。

en: Older plugins used a ``run`` method as their main body/work:
ja: 古いプラグインでは、``run`` メソッドを主要な本文/作業として使用していました。

en: Ansible 2.0 did not pass passwords to older plugins, so vaults were unavailable. Most of the work now  happens in the ``get_vars`` method which is called from the VariableManager when needed.
ja: Ansible 2.0 は古いプラグインにパスワードを渡さなかったため、vault は利用できませんでした。ほとんどの作業は、必要に応じて VariableManager から呼び出される ``get_vars`` メソッドで実行されるようになりました。

en: The parameters are:
ja: パラメーターは以下のとおりです。

en: loader: Ansible's DataLoader. The DataLoader can read files, auto-load JSON/YAML and decrypt vaulted data, and cache read files.
ja: loader: Ansible の DataLoader。DataLoader は、ファイルの読み取り、JSON/YAML の自動読み込み、vault を使用したデータの復号、および読み取りファイルのキャッシュを行うことができます。

en: path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data in reference to them. ``get_vars`` will be called at least once per available path.
ja: path: これはすべてのインベントリーソースと現在のプレイの Playbook ディレクトリーの「ディレクトリーデータ」であるため、それを参照するデータを検索することができます。``get_vars`` は、利用可能なパスごとに最低 1 回呼び出されます。

en: entities: these are host or group names that are pertinent to the variables needed. The plugin will get called once for hosts and again for groups.
ja: entities: 必要な変数に関連付けられるホスト名またはグループ名です。プラグインはホストに対して 1 回呼び出され、グループに対して再度呼び出されます。

en: This ``get_vars`` method just needs to return a dictionary structure with the variables.
ja: この ``get_vars`` メソッドは変数を含むディクショナリー構造を返す必要があります。

en: Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a task. This avoids the costly 'always execute' behavior that occurred during inventory construction in older versions of Ansible. Since Ansible version 2.10, vars plugin execution can be toggled by the user to run when preparing to execute a task or after importing an inventory source.
ja: Ansible バージョン 2.4 以降、タスク実行の準備時に必要に応じて vars プラグインのみを実行します。これにより、古いバージョンの Ansible のインベントリー構築中に発生した、費用のかかる「常に実行」動作が回避されます。Ansible バージョン 2.10 以降、vars プラグインの実行は、タスクの実行準備時またはインベントリーソースのインポート後に実行するようにユーザーが切り替えることができます。

en: You can create vars plugins that are not enabled by default using the class variable ``REQUIRES_ENABLED``. If your vars plugin resides in a collection, it cannot be enabled by default. You must use ``REQUIRES_ENABLED`` in all collections-based vars plugins. To require users to enable your plugin, set the class variable ``REQUIRES_ENABLED``:
ja: クラス変数 ``REQUIRES_ENABLED`` を使用して、デフォルトで有効になっていない vars プラグインを作成できます。vars プラグインがコレクションに存在する場合は、デフォルトで有効にはできません。すべてのコレクションベースの vars プラグインで ``REQUIRES_ENABLED`` を使用する必要があります。ユーザーがプラグインを有効にするには、クラス変数 ``REQUIRES_ENABLED`` を設定します。

en: Include the ``vars_plugin_staging`` documentation fragment to allow users to determine when vars plugins run.
ja: ``vars_plugin_staging`` ドキュメントフラグメントを追加して、ユーザーが when vars プラグインの実行を判別できるようにします。

en: For example vars plugins, see the source code for the `vars plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_.
ja: vars プラグインの例は、`Ansible Core に含まれる vars プラグイン <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ のソースコードを参照してください。

en: Learn about how to develop dynamic inventory sources
ja: 動的インベントリーソースの開発方法について

en: Ansible module architecture
ja: Ansible モジュールのアーキテクチャー

en: If you are working on the ``ansible-core`` code, writing an Ansible module, or developing an action plugin, you may need to understand how Ansible's program flow executes. If you are just using Ansible Modules in playbooks, you can skip this section.
ja: ``ansible-core`` コードを使用している場合、Ansible モジュールの作成、またはアクションプラグインの開発では、Ansible のプログラムフローがどのように実行されるかを理解しないといけない場合があります。Playbook で Ansible モジュールを使用しているだけの場合は、このセクションをスキップできます。

en: Types of modules
ja: モジュールの種類

en: Ansible supports several different types of modules in its code base. Some of these are for backwards compatibility and others are to enable flexibility.
ja: Ansible は、コードベースでいくつかの異なるタイプのモジュールをサポートしています。下位互換性のためのものもあり、柔軟性を可能にするものもあります。

en: Action plugins look like modules to anyone writing a playbook. Usage documentation for most action plugins lives inside a module of the same name. Some action plugins do all the work, with the module providing only documentation. Some action plugins execute modules. The ``normal`` action plugin executes modules that don't have special action plugins. Action plugins always execute on the controller.
ja: action プラグインは、Playbook を作成する人にとってはモジュールのように見えます。ほとんどの action プラグインの使用方法に関するドキュメントは、同じ名前のモジュール内にあります。action プラグインの中には、すべての作業を行なうものもありますが、このモジュールはドキュメントのみを提供します。一部の action プラグインはモジュールを実行します。action プラグイン ``normal`` は、特別な action プラグインを持たないモジュールを実行します。action プラグインは常にコントローラーで実行します。

en: Some action plugins do all their work on the controller. For example, the :ref:`debug <debug_module>` action plugin (which prints text for the user to see) and the :ref:`assert <assert_module>` action plugin (which tests whether values in a playbook satisfy certain criteria) execute entirely on the controller.
ja: action プラグインによってコントローラーですべての作業が機能します。たとえば、action プラグイン :ref:`debug <debug_module>` (ユーザーに表示できるようにテキストを出力する) および action プラグイン :ref:`assert <assert_module>` (Playbook の値が特定の基準を満たすかどうかのテスト) など、コントローラー上で完全に実行します。

en: Most action plugins set up some values on the controller, then invoke an actual module on the managed node that does something with these values. For example, the :ref:`template <template_module>` action plugin takes values from the user to construct a file in a temporary location on the controller using variables from the playbook environment. It then transfers the temporary file to a temporary file on the remote system. After that, it invokes the :ref:`copy module <copy_module>` which operates on the remote system to move the file into its final location, sets file permissions, and so on.
ja: ほとんどのアクションプラグインは、コントローラーにいくつかの値を設定した後、管理ノードで実際のモジュールを呼び出して、これらの値を使用して何かを行います。たとえば、action プラグイン :ref:`template <template_module>` は、ユーザーから値を受け取り、Playbook 環境からの変数を使用して、コントローラーの一時的な場所にファイルを作成します。その後、その一時ファイルを、リモートシステムの一時ファイルに転送します。その後、リモートシステム上で動作する :ref:`copy モジュール <copy_module>` を起動して、ファイルを最終的な場所に移動させ、ファイルのパーミッションを設定するなどの作業を行います。

en: New-style modules
ja: 新スタイルのモジュール

en: All of the modules that ship with Ansible fall into this category. While you can write modules in any language, all official modules (shipped with Ansible) use either Python or PowerShell.
ja: Ansible に同梱されるモジュールはすべてこのカテゴリーに分類されます。モジュールは任意の言語で記述できますが、(Ansible に同梱されている) 正式なモジュールはすべて Python または PowerShell を使用します。

en: New-style modules have the arguments to the module embedded inside of them in some manner. Old-style modules must copy a separate file over to the managed node, which is less efficient as it requires two over-the-wire connections instead of only one.
ja: 新しいスタイルのモジュールには、なんらかの方法で実装されているモジュールに引数があります。古いスタイルのモジュールは、管理ノードに個別のファイルを管理ノードにコピーする必要があります。これは、1 つの接続ではなく、ネットワーク上の接続が 2 つ必要であるため、効率が悪くなります。

en: New-style Python modules use the :ref:`Ansiballz` framework for constructing modules. These modules use imports from :code:`ansible.module_utils` to pull in boilerplate module code, such as argument parsing, formatting of return values as :term:`JSON`, and various file operations.
ja: 新しいスタイルの Python モジュールは、モジュールの構築に :ref:`Ansiballz` フレームワークを使用します。これらのモジュールは、:code:`ansible.module_utils` からインポートを使用し、引数の解析、:term:`JSON` などのさまざまなファイル操作の戻り値のフォーマットなど、boilerplate モジュールコードとして取得します。

en: In Ansible, up to version 2.0.x, the official Python modules used the :ref:`module_replacer` framework.  For module authors, :ref:`Ansiballz` is largely a superset of :ref:`module_replacer` functionality, so you usually do not need to understand the differences between them.
ja: バージョン 2.0.x までの Ansible では、公式の Python モジュールが :ref:`module_replacer` フレームワークを使用していました。:ref:`Ansiballz` は、:ref:`module_replacer` 機能の上位セットであるため、通常はモジュール作成者がこれらの違いを理解する必要はありません。

en: New-style PowerShell modules use the :ref:`module_replacer` framework for constructing modules. These modules get a library of PowerShell code embedded in them before being sent to the managed node.
ja: 新しいスタイルの PowerShell モジュールは、モジュールの構築に :ref:`module_replacer` フレームワークを使用します。これらのモジュールは、管理ノードに送信される前にそれらに組み込まれている PowerShell コードのライブラリーを取得します。

en: JSONARGS modules
ja: JSONARGS モジュール

en: These modules are scripts that include the string ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` in their body. This string is replaced with the JSON-formatted argument string. These modules typically set a variable to that value like this:
ja: これらのモジュールは、本文に文字列 ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` が含まれるスクリプトです。この文字列は JSON 形式の引数文字列に置き換えられます。これらのモジュールは、通常、変数を以下のような値に設定します。

en: Which is expanded as:
ja: これは以下のように展開されます。

en: Ansible outputs a :term:`JSON` string with bare quotes. Double quotes are used to quote string values, double quotes inside of string values are backslash escaped, and single quotes may appear unescaped inside of a string value. To use JSONARGS, your scripting language must have a way to handle this type of string. The example uses Python's triple quoted strings to do this. Other scripting languages may have a similar quote character that won't be confused by any quotes in the JSON or it may allow you to define your own start-of-quote and end-of-quote characters. If the language doesn't give you any of these then you'll need to write a :ref:`non-native JSON module <flow_want_json_modules>` or :ref:`Old-style module <flow_old_style_modules>` instead.
ja: Ansible は、:term:`JSON` の文字列を引用符なしで出力します。文字列値の引用には二重引用符が使用され、文字列値の中の二重引用符はバックスラッシュでエスケープされ、文字列値の中の一重引用符はエスケープされずに表示されることがあります。JSONARGS を使用するには、スクリプト言語がこの種の文字列を処理する方法を備えている必要があります。この例では、Python の三重引用符文字列を使用しています。他のスクリプト言語では、JSON 内の引用符と混同されないような同様の引用符文字が用意されていたり、独自の引用開始文字や引用終了文字を定義できたりする場合があります。お使いの言語がこれを提供していない場合は、代わりに :ref:`非ネイティブ JSON モジュール <flow_want_json_modules>` または :ref:`古いスタイルのモジュール <flow_old_style_modules>` を記述する必要があります。

en: These modules typically parse the contents of ``json_arguments`` using a JSON library and then use them as native variables throughout the code.
ja: これらのモジュールは通常、JSON ライブラリーを使用して ``json_arguments`` のコンテンツを解析し、次にコード全体でネイティブ変数として使用します。

en: Non-native want JSON modules
ja: ネイティブ以外の JSON モジュール

en: If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats it as a non-native module that accepts a filename as its only command line parameter. The filename is for a temporary file containing a :term:`JSON` string containing the module's parameters. The module needs to open the file, read and parse the parameters, operate on the data, and print its return data as a JSON encoded dictionary to stdout before exiting.
ja: モジュールに文字列 ``WANT_JSON`` があると、Ansible は、ファイル名をコマンドラインパラメーターとしてのみ許可する非ネイティブモジュールとして扱います。ファイル名は、モジュールのパラメーターを含む :term:`JSON` 文字列を含む一時的なファイル向けです。モジュールはファイルを開き、パラメーターを読み取りおよび解析し、データで操作し、終了する前にその戻り値を JSON エンコードディレクトリーとして stdout に出力する必要があります。

en: These types of modules are self-contained entities. As of Ansible 2.1, Ansible only modifies them to change a shebang line if present.
ja: これらのモジュールタイプは自己完結型エンティティーです。Ansible 2.1 以降、Ansible では、存在する場合にのみ、シバン行を変更するようにそれらを変更します。

en: Examples of Non-native modules written in ruby are in the `Ansible for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ repository.
ja: Ruby で書かれた非ネイティブモジュールの例は、`Ansible for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ リポジトリーにあります。

en: Binary modules
ja: バイナリーモジュール

en: From Ansible 2.2 onwards, modules may also be small binary programs. Ansible doesn't perform any magic to make these portable to different systems so they may be specific to the system on which they were compiled or require other binary runtime dependencies. Despite these drawbacks, you may have to compile a custom module against a specific binary library if that's the only way to get access to certain resources.
ja: Ansible 2.2 以降、モジュールは小規模のバイナリープログラムでもあります。Ansible は、これらを異なるシステムに移植できるようにする機能がないため、コンパイルされたシステムに固有のものであったり、他のバイナリーランタイムに依存したものが必要であったりします。このような欠点はありますが、特定のリソースにアクセスするための唯一の方法であれば、特定のバイナリーライブラリーに対するカスタムモジュールのコンパイルが必要になる場合があります。

en: Binary modules take their arguments and return data to Ansible in the same way as :ref:`want JSON modules <flow_want_json_modules>`.
ja: バイナリモジュールは、引数を取り、:ref:`want JSON モジュール <flow_want_json_modules>` と同じ方法でデータを Ansible に返します。

en: One example of a `binary module <https://github.com/ansible/ansible/blob/devel/test/integration/targets/binary_modules/library/helloworld.go>`_ written in go.
ja: Go で記述された ` バイナリーモジュール <https://github.com/ansible/ansible/blob/devel/test/integration/targets/binary_modules/library/helloworld.go>`_ の一例

en: Old-style modules
ja: 古いスタイルのモジュール

en: Old-style modules are similar to :ref:`want JSON modules <flow_want_json_modules>`, except that the file that they take contains ``key=value`` pairs for their parameters instead of :term:`JSON`. Ansible decides that a module is old-style when it doesn't have any of the markers that would show that it is one of the other types.
ja: 古いスタイルのモジュールは、:ref:`want JSON モジュール <flow_want_json_modules>` と似ていますが、使用するファイルが :term:`JSON` ではなく ``key=value`` のペアをパラメータに含んでいる点が異なります。Ansible は、モジュールに他のタイプの 1 つであることを示すマーカーがないと、そのモジュールが古いスタイルであると判断します。

en: How modules are executed
ja: モジュールの実行方法

en: When a user uses :program:`ansible` or :program:`ansible-playbook`, they specify a task to execute. The task is usually the name of a module along with several parameters to be passed to the module. Ansible takes these values and processes them in various ways before they are finally executed on the remote machine.
ja: :program:`ansible` または :program:`ansible-playbook` を使用する場合は、実行するタスクを指定します。タスクは通常、モジュールに渡す複数のパラメーターを持つモジュールの名前です。Ansible はこれらの値を取得し、さまざまな方法で処理してから、最終的にリモートマシンで実行されます。

en: The TaskExecutor receives the module name and parameters that were parsed from the :term:`playbook <playbooks>` (or from the command line in the case of :command:`/usr/bin/ansible`). It uses the name to decide whether it's looking at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>` and passes the name, variables, and other information about the task and play to that Action Plugin for further processing.
ja: TaskExecutor は、:term:`playbook <playbooks>` (:command:`/usr/bin/ansible` の場合はコマンドライン) から解析されたモジュール名とパラメーターを受け取ります。これは、モジュールを見て、または :ref:`Action Plugin <flow_action_plugins>` を見ているかを判断するために名前を使用します。モジュールの場合は、:ref:`Normal Action Plugin <flow_normal_action_plugin>` を読み込み、タスクとプレイに関する名前、変数、およびその他の情報をそのアクションプラグインに渡して、さらに処理します。

en: The ``normal`` action plugin
ja: action プラグイン ``normal``

en: The ``normal`` action plugin executes the module on the remote host. It is the primary coordinator of much of the work to actually execute the module on the managed machine.
ja: action プラグイン ``normal`` は、リモートホストでモジュールを実行します。管理マシンでモジュールを実際に実行する多くの作業に対する主要な調整役です。

en: It loads the appropriate connection plugin for the task, which then transfers or executes as needed to create a connection to that host.
ja: タスクに適切な接続プラグインを読み込み、そのホストへの接続を作成するために必要に応じて転送や実行を行います。

en: It adds any internal Ansible properties to the module's parameters (for instance, the ones that pass along ``no_log`` to the module).
ja: モジュールのパラメーターに、Ansible の内部プロパティーを追加します (たとえば ``no_log`` をモジュールに渡すものなど)。

en: It works with other plugins (connection, shell, become, other action plugins) to create any temporary files on the remote machine and cleans up afterwards.
ja: これは、他のプラグイン (connection、shell、become、その他の action プラグイン) と連携して、リモートマシンに一時ファイルを作成し、後で削除します。

en: It pushes the module and module parameters to the remote host, although the :ref:`module_common <flow_executor_module_common>` code described in the next section decides which format those will take.
ja: これに、モジュールおよびモジュールパラメーターがリモートホストにプッシュされますが、次のセクションで説明する :ref:`module_common <flow_executor_module_common>` コードが、どの形式を取るのか決定します。

en: It handles any special cases regarding modules (for instance, async execution, or complications around Windows modules that must have the same names as Python modules, so that internal calling of modules from other Action Plugins work.)
ja: モジュールに関する特殊なケースを処理します (たとえば、非同期実行や、Python モジュールと同じ名前を持たなければならない Windows モジュールの複雑さなど。これにより、他の action プラグインからのモジュールの内部呼び出しが機能します)。

en: Much of this functionality comes from the `BaseAction` class, which lives in :file:`plugins/action/__init__.py`. It uses the ``Connection`` and ``Shell`` objects to do its work.
ja: この機能の多くは、`BaseAction` クラス (:file:`plugins/action/__init__.py` にある) から取得されます。これは、``Connection`` オブジェクトおよび ``Shell`` オブジェクトを使用して作業を行います。

en: When :term:`tasks <tasks>` are run with the ``async:`` parameter, Ansible uses the ``async`` Action Plugin instead of the ``normal`` Action Plugin to invoke it. That program flow is currently not documented. Read the source for information on how that works.
ja: :term:`tasks <tasks>` を ``async:`` パラメーターで実行している場合、Ansible は、action プラグイン ``normal`` の代わりに ``async`` を使用してそれを呼び出します。そのプログラムフローは現在文書化されていません。それがどのように機能するかについては、ソースをお読みください。

en: Code in :file:`executor/module_common.py` assembles the module to be shipped to the managed node. The module is first read in, then examined to determine its type:
ja: :file:`executor/module_common.py` のコードは、管理ノードに同梱するモジュールをアセンブルします。まず、モジュールが最初に読み込まれ、その後はそのタイプを判断します。

en: :ref:`PowerShell <flow_powershell_modules>` and :ref:`JSON-args modules <flow_jsonargs_modules>` are passed through :ref:`Module Replacer <module_replacer>`.
ja: :ref:`PowerShell <flow_powershell_modules>` および :ref:`JSON-args modules <flow_jsonargs_modules>` は、:ref:`Module Replacer <module_replacer>` 経由で渡されます。

en: New-style :ref:`Python modules <flow_python_modules>` are assembled by :ref:`Ansiballz`.
ja: 新しいスタイルの :ref:`Python modules <flow_python_modules>` は :ref:`Ansiballz` によりアセンブルされます。

en: :ref:`Non-native-want-JSON <flow_want_json_modules>`, :ref:`Binary modules <flow_binary_modules>`, and :ref:`Old-Style modules <flow_old_style_modules>` aren't touched by either of these and pass through unchanged.
ja: :ref:`Non-native-want-JSON <flow_want_json_modules>`、:ref:`バイナリーモジュール <flow_binary_modules>`、および:ref:`古いスタイルのモジュール <flow_old_style_modules>` は、これらのどちらにも触れられず、変更されずにそのまま通過します。

en: After the assembling step, one final modification is made to all modules that have a shebang line. Ansible checks whether the interpreter in the shebang line has a specific path configured via an ``ansible_$X_interpreter`` inventory variable. If it does, Ansible substitutes that path for the interpreter path given in the module. After this, Ansible returns the complete module data and the module type to the :ref:`Normal Action <flow_normal_action_plugin>` which continues execution of the module.
ja: アセンブル手順後、シバン行を持つすべてのモジュールに最終変更が行われます。Ansible は、シバン行内のインタープリターに ``ansible_$X_interpreter`` インベントリー変数を介して特定のパスが設定されているかどうかを確認します。パスがある場合、Ansible は、そのパスを、そのモジュールに指定されているインタープリターパスに置き換えます。その後、Ansible は完全なモジュールデータを返し、モジュールタイプを :ref:`通常のアクション <flow_normal_action_plugin>` に返し、モジュールの実行を続行します。

en: Assembler frameworks
ja: アセンブラーフレームワーク

en: Ansible supports two assembler frameworks: Ansiballz and the older Module Replacer.
ja: Ansible は、2 つのアセンブラフレームワーク (Ansiballz と古い Module Replacer) をサポートしています。

en: Module Replacer framework
ja: Module Replacer フレームワーク

en: The Module Replacer framework is the original framework implementing new-style modules, and is still used for PowerShell modules. It is essentially a preprocessor (like the C Preprocessor for those familiar with that programming language). It does straight substitutions of specific substring patterns in the module file. There are two types of substitutions:
ja: モジュール置換フレームワークは、新しいスタイルモジュールを実装し、引き続き PowerShell モジュール向けに使用されています。基本的には、(そのプログラミング言語に精通している C プロセッサーなど) です。モジュールファイル内の特定の従属文字列パターンを直接置換します。置換には 2 つのタイプがあります。

en: Replacements that only happen in the module file. These are public replacement strings that modules can utilize to get helpful boilerplate or access to arguments.
ja: モジュールファイルでのみ実行する置換。モジュールは、便利な boilerplate や引数へのアクセスに使用できるパブリックの置換文字列です。

en: :code:`from ansible.module_utils.MOD_LIB_NAME import *` is replaced with the contents of the :file:`ansible/module_utils/MOD_LIB_NAME.py`  These should only be used with :ref:`new-style Python modules <flow_python_modules>`.
ja: :code:`from ansible.module_utils.MOD_LIB_NAME import *` は、:file:`ansible/module_utils/MOD_LIB_NAME.py` の内容に置き換えます。これらは、:ref:`new-style Python modules <flow_python_modules>` と併用する必要があります。

en: :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` is equivalent to :code:`from ansible.module_utils.basic import *` and should also only apply to new-style Python modules.
ja: :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` は、:code:`from ansible.module_utils.basic import *` と同等で、新しいスタイルの Python モジュールのみに適用する必要があります。

en: :code:`# POWERSHELL_COMMON` substitutes the contents of :file:`ansible/module_utils/powershell.ps1`. It should only be used with :ref:`new-style Powershell modules <flow_powershell_modules>`.
ja: :code:`# POWERSHELL_COMMON` は、:file:`ansible/module_utils/powershell.ps1` の内容を置き換えます。これは、:ref:`新しいスタイルの Powershell モジュール <flow_powershell_modules>` と併用する必要があります。

en: Replacements that are used by ``ansible.module_utils`` code. These are internal replacement patterns. They may be used internally, in the above public replacements, but shouldn't be used directly by modules.
ja: ``ansible.module_utils`` コードにより使用される代替品。これらは内部交換パターンです。これらは、上記のパブリック置換で内部的に使用できますが、モジュールで直接使用しないでください。

en: :code:`"<<ANSIBLE_VERSION>>"` is substituted with the Ansible version.  In :ref:`new-style Python modules <flow_python_modules>` under the :ref:`Ansiballz` framework the proper way is to instead instantiate an `AnsibleModule` and then access the version from :attr:``AnsibleModule.ansible_version``.
ja: :code:`"<<ANSIBLE_VERSION>>"` は、Ansible バージョンに置き換えられます。:ref:`Ansiballz` フレームワークの下の :ref:`new-style Python modules <flow_python_modules>` で適切な方法は、代わりに `AnsibleModule` をインスタンス化し、:attr:``AnsibleModule.ansible_version`` からバージョンにアクセスすることです。

en: :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` is substituted with a string which is the Python ``repr`` of the :term:`JSON` encoded module parameters. Using ``repr`` on the JSON string makes it safe to embed in a Python file. In new-style Python modules under the Ansiballz framework this is better accessed by instantiating an `AnsibleModule` and then using :attr:`AnsibleModule.params`.
ja: :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` は、:term:`JSON` でエンコードされたモジュールパラメーターの Python ``repr`` の文字列に置き換えます。JSON 文字列で ``repr`` を使用すると、Python ファイルに安全に埋め込むことができます。Ansiballz フレームワークの新しいスタイル Python モジュールでは、`AnsibleModule` をインスタンス化してから :attr:`AnsibleModule.params` を使用することで、これはより適切にアクセスされます。

en: :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is a comma separated list of file systems which have a file system dependent security context in SELinux. In new-style Python modules, if you really need this you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed from a comma separated string of file system names to an actual python list of filesystem names.
ja: :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` は、SELinux にファイルシステムに依存するセキュリティーコンテキストがあるファイルシステムのコンマ区切りの一覧である文字列を置き換えます。新しいスタイルの Python モジュールで `AnsibleModule` をインスタンス化してから、:attr:`AnsibleModule._selinux_special_fs` を使用してください。また、この変数は、ファイルシステム名のコンマ区切りの文字列から、ファイルシステム名の実際の python のリストに変更されています。

en: :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module parameters as a JSON string. Care must be taken to properly quote the string as JSON data may contain quotes. This pattern is not substituted in new-style Python modules as they can get the module parameters another way.
ja: :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` はモジュールパラメーターを JSON 文字列として置き換えます。JSON データには引用符が含まれている可能性があるため、文字列を適切に引用符で囲むように注意する必要があります。このパターンは、モジュールパラネーターを別の方法で取得できるため、新しいスタイルの Python モジュールでは置き換えられません。

en: The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the ``syslog_facility`` which was named in :file:`ansible.cfg` or any ``ansible_syslog_facility`` inventory variable that applies to this host.  In new-style Python modules this has changed slightly. If you really need to access it, you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._syslog_facility` to access it. It is no longer the actual syslog facility and is now the name of the syslog facility. See the :ref:`documentation on internal arguments <flow_internal_arguments>` for details.
ja: 文字列 :code:`syslog.LOG_USER` は、:file:`ansible.cfg` またはこのホストに適用される ``ansible_syslog_facility`` インベントリー変数で囲まれている ``syslog_facility`` に置き換えられます。新しいスタイルの Python モジュールでは、これは若干変更になりました。本当にアクセスする必要がある場合は、`AnsibleModule` をインスタンス化し、その後 :attr:`AnsibleModule._syslog_facility` を使用してアクセスする必要があります。これは実際の syslog 機能ではなく、syslog 機能の名前になります。詳細は、「:ref:`内部引数のドキュメント <flow_internal_arguments>`」を参照してください。

en: Ansiballz framework
ja: Ansiballz フレームワーク

en: The Ansiballz framework was adopted in Ansible 2.1 and is used for all new-style Python modules. Unlike the Module Replacer, Ansiballz uses real Python imports of things in :file:`ansible/module_utils` instead of merely preprocessing the module. It does this by constructing a zipfile -- which includes the module file, files in :file:`ansible/module_utils` that are imported by the module, and some boilerplate to pass in the module's parameters. The zipfile is then Base64 encoded and wrapped in a small Python script which decodes the Base64 encoding and places the zipfile into a temp directory on the managed node. It then extracts just the Ansible module script from the zip file and places that in the temporary directory as well. Then it sets the PYTHONPATH to find Python modules inside of the zip file and imports the Ansible module as the special name, ``__main__``. Importing it as ``__main__`` causes Python to think that it is executing a script rather than simply importing a module. This lets Ansible run both the wrapper script and the module code in a single copy of Python on the remote machine.
ja: Ansiblez フレームワークは Ansible 2.1 で採用され、すべての新しいスタイルの Python モジュールに使用されます。Module Replacer とは異なり、Ansiballz は、単にモジュールを前処理するだけではなく、:file:`ansible/module_utils` に含まれるものを実際に Python でインポートします。これを行うには、zipfile を構築します。これには、モジュールファイル、モジュールがインポートする :file:`ansible/module_utils` のファイル、およびモジュールのパラメーターを渡す boilerplate が含まれます。その後、zipfile は Base64 でエンコードされ、小さな Python スクリプトでラップされます。このスクリプトは Base64 エンコードをデコードし、zipfile を管理対象ノードの一時ディレクトリーに配置します。その後、zip ファイルから Ansible モジュールスクリプトのみを抽出し、一時ディレクトリーに配置します。その後、PYTHONPATH を設定して、zip ファイルから Python モジュールを検索し、Ansible モジュールを特殊な名前 ``__main__`` としてインポートします。``__main__`` としてインポートすると、Python は単にモジュールをインポートするのではなく、スクリプトを実行していると見なすようになります。これにより、Ansible は、ラッパースクリプトとモジュールコードの両方を、リモートマシンの Python の単一コピーで実行できます。

en: Ansible wraps the zipfile in the Python script for two reasons:
ja: Ansible が Python スクリプトで zip ファイルをラップするには、以下の 2 つの理由があります。

en: for compatibility with Python 2.6 which has a less functional version of Python's ``-m`` command line switch.
ja: Python の ``-m`` コマンドラインスイッチの機能が少ない Python 2.6 との互換性のため。

en: so that pipelining will function properly. Pipelining needs to pipe the Python module into the Python interpreter on the remote node. Python understands scripts on stdin but does not understand zip files.
ja: パイプ処理が適切に機能します。Pipelining は Python モジュールをリモートノード上の Python インタープリターにパイプする必要があります。Python は stdin のスクリプトを理解しますが、zip ファイルを理解しません。

en: Prior to Ansible 2.7, the module was executed via a second Python interpreter instead of being executed inside of the same process. This change was made once Python-2.4 support was dropped to speed up module execution.
ja: Ansible 2.7 より前のバージョンでは、同じプロセス内で実行されるのではなく 2 つ目の Python インタープリター経由で実行されます。この変更は、Python-2.4 サポートが破棄され、モジュール実行のスピードを高めました。

en: In Ansiballz, any imports of Python modules from the :py:mod:`ansible.module_utils` package trigger inclusion of that Python file into the zipfile. Instances of :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` in the module are turned into :code:`from ansible.module_utils.basic import *` and :file:`ansible/module-utils/basic.py` is then included in the zipfile. Files that are included from :file:`module_utils` are themselves scanned for imports of other Python modules from :file:`module_utils` to be included in the zipfile as well.
ja: Ansiballzでは、:py:mod:`ansible.module_utils` パッケージからの Python モジュールのインポートにより、その Python ファイルが zip ファイルに追加されます。モジュール内の :code:`#<<INCLUDE_ANSIBLE_MODULE_COMMON>>` のインスタンスは :code:`from ansible.module_utils.basic import *` に変換され、その後 :file:`ansible/module-utils/basic.py` が zip ファイルに追加されます。:file:`module_utils` から追加されるファイルは、それ自体が :file:`module_utils` からの他の Python モジュールのインポートをスキャンし、同じように zip ファイルに追加します。

en: At present, the Ansiballz Framework cannot determine whether an import should be included if it is a relative import. Always use an absolute import that has :py:mod:`ansible.module_utils` in it to allow Ansiballz to determine that the file should be included.
ja: 現状、Aweraiballz Framework は、相対インポートの場合にインポートを含める必要があるかどうかを判別できません。常に、その中に :py:mod:`ansible.module_utils` がある絶対インポートを使用して、このファイルを同梱する必要があると判断することができます。

en: Passing args
ja: 引数を渡す

en: Arguments are passed differently by the two frameworks:
ja: 以下の 2 つのフレームワークでは、引数の渡し方が異なります。

en: In :ref:`module_replacer`, module arguments are turned into a JSON-ified string and substituted into the combined module file.
ja: :ref:`module_replacer` では、モジュールの引数は JSON 化された文字列に変換され、結合されたモジュールファイルに置き換えられます。

en: In :ref:`Ansiballz`, the JSON-ified string is part of the script which wraps the zipfile. Just before the wrapper script imports the Ansible module as ``__main__``, it monkey-patches the private, ``_ANSIBLE_ARGS`` variable in ``basic.py`` with the variable values. When a :class:`ansible.module_utils.basic.AnsibleModule` is instantiated, it parses this string and places the args into :attr:`AnsibleModule.params` where it can be accessed by the module's other code.
ja: :ref:`Ansiballz` では、JSON 化された文字列は、zip ファイルをラップするスクリプトの一部です。ラッパースクリプトが Ansible モジュールを ``__main__`` としてインポートする直前に、``basic.py`` のプライベート変数 ``_ANSIBLE_ARGS`` を変数値でモンキーパッチしています。:class:`ansible.module_utils.basic.AnsibleModule` がインスタンス化されると、この文字列を解析し、引数を :attr:`AnsibleModule.params` に配置し、モジュールの他のコードがアクセスできる場所に置きます。

en: If you are writing modules, remember that the way we pass arguments is an internal implementation detail: it has changed in the past and will change again as soon as changes to the common module_utils code allow Ansible modules to forgo using :class:`ansible.module_utils.basic.AnsibleModule`. Do not rely on the internal global ``_ANSIBLE_ARGS`` variable.
ja: モジュールを作成している場合は、引数を渡す方法は内部実装の詳細であることに注意してください。これは過去に変更されており、共通のモジュールユーティリティーコードを変更すると、Ansible モジュールが :class:`ansible.module_utils.basic.AnsibleModule` の使用をやめるとすぐに再び変更されます。内部グローバル変数 ``_ANSIBLE_ARGS`` に依存しないでください。

en: Very dynamic custom modules which need to parse arguments before they instantiate an ``AnsibleModule`` may use ``_load_params`` to retrieve those parameters. Although ``_load_params`` may change in breaking ways if necessary to support changes in the code, it is likely to be more stable than either the way we pass parameters or the internal global variable.
ja: ``AnsibleModule`` をインスタンス化する前に引数を解析する必要のある非常に動的なカスタムモジュールは、``_load_params`` を使用してこれらのパラメーターを取得する場合があります。コードの変更をサポートする必要がある場合は、``_load_params`` が破壊的な方法で変更する可能性がありますが、パラメーターまたは内部グローバル変数を渡す方法よりも安定している可能性があります。

en: Prior to Ansible 2.7, the Ansible module was invoked in a second Python interpreter and the arguments were then passed to the script over the script's stdin.
ja: Ansible 2.7 より前のバージョンでは、Ansible モジュールは 2 番目の Python インタープリターで呼び出され、引数はスクリプトの標準入力 (stdin) を介してスクリプトに渡されていました。

en: Internal arguments
ja: 内部引数

en: Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to the module beyond those which the user specified in the playbook. These additional arguments are internal parameters that help implement global Ansible features. Modules often do not need to know about these explicitly as the features are implemented in :py:mod:`ansible.module_utils.basic` but certain features need support from the module so it's good to know about them.
ja: :ref:`module_replacer` および :ref:`Ansiballz` の両方は、Playbook で指定したユーザー以外に追加の引数をモジュールに送信します。これらの追加の引数は、Ansible のグローバル機能の実装に役立つ内部パラメーターです。これらの機能は、:py:mod:`ansible.module_utils.basic` に実装されているため、モジュールが明示的に理解する必要がないことがしばしばありますが、機能についてある程度理解できるように、モジュールから特定の機能のサポートが必要になります。

en: The internal arguments listed here are global. If you need to add a local internal argument to a custom module, create an action plugin for that specific module - see ``_original_basename`` in the `copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an example.
ja: ここに記載されている内部引数はグローバルです。カスタムモジュールにローカルの内部引数を追加する必要がある場合は、その特定のモジュールに action プラグインを作成してください。例は、「`copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_」の「``_original_basename``」を参照してください。

en: Boolean. Set to True whenever a parameter in a task or play specifies ``no_log``. Any module that calls :py:meth:`AnsibleModule.log` handles this automatically. If a module implements its own logging then it needs to check this value. To access in a module, instantiate an ``AnsibleModule`` and then check the value of :attr:`AnsibleModule.no_log`.
ja: ブール値。タスクまたはプレイのパラメーターを ``no_log`` に指定した場合は常に True に設定します。:py:meth:`AnsibleModule.log` を呼び出すモジュールが自動的にこれを処理します。モジュールがその独自のロギングを実装した場合は、この値を確認する必要があります。モジュールにアクセスするには、``AnsibleModule`` をインスタンス化して、:attr:`AnsibleModule.no_log` の値を確認します。

en: ``no_log`` specified in a module's argument_spec is handled by a different mechanism.
ja: モジュールの argument_spec で指定された ``no_log`` は別のメカニズムで処理されます。

en: Boolean. Turns more verbose logging on or off and turns on logging of external commands that the module executes. If a module uses :py:meth:`AnsibleModule.debug` rather than :py:meth:`AnsibleModule.log` then the messages are only logged if ``_ansible_debug`` is set to ``True``. To set, add ``debug: True`` to :file:`ansible.cfg` or set the environment variable :envvar:`ANSIBLE_DEBUG`. To access in a module, instantiate an ``AnsibleModule`` and access :attr:`AnsibleModule._debug`.
ja: ブール値。詳細なロギングをオンまたはオフにし、モジュールが実行する外部コマンドのロギングを有効にします。モジュールが :py:meth:`AnsibleModule.log` ではなく :py:meth:`AnsibleModule.debug` を使用する場合は、``_ansible_debug`` が ``True`` に設定されている場合にのみメッセージがログに記録されます。設定するには、``debug: True`` を :file:`ansible.cfg` に追加するか、環境変数 :envvar:`ANSIBLE_DEBUG` を設定します。モジュールにアクセスするには、``AnsibleModule`` をインスタンス化し、:attr:`AnsibleModule._debug` にアクセスします。

en: Boolean. If a module supports it, tells the module to show a unified diff of changes to be made to templated files. To set, pass the ``--diff`` command line option. To access in a module, instantiate an `AnsibleModule` and access :attr:`AnsibleModule._diff`.
ja: ブール値。モジュールがサポートする場合は、モジュールに対し、テンプレート化されたファイルに加えられた変更の差異を統合するようにモジュールに指示します。設定するには、``--diff`` コマンドラインオプションを渡します。モジュールにアクセスするには、`AnsibleModule` をインスタンス化して、:attr:`AnsibleModule._diff` にアクセスしてください。

en: Unused. This value could be used for finer grained control over logging.
ja: 未使用。この値は、ログをより細かく制御するために使用できます。

en: List. Names of filesystems which should have a special SELinux context. They are used by the `AnsibleModule` methods which operate on files (changing attributes, moving, and copying). To set, add a comma separated string of filesystem names in :file:`ansible.cfg`::
ja: 一覧。特別な SELinux コンテキストを持つ必要があるファイルシステムの名前。名前はファイル (属性の変更、移動、コピー) で操作する `AnsibleModule` メソッドによって使用されます。設定するには、:file:`ansible.cfg` に、ファイル名のコンマ区切りの文字列を追加します。

en: Most modules can use the built-in ``AnsibleModule`` methods to manipulate files. To access in a module that needs to know about these special context filesystems, instantiate an ``AnsibleModule`` and examine the list in :attr:`AnsibleModule._selinux_special_fs`.
ja: ほとんどのモジュールは、ファイルを操作する組み込み ``AnsibleModule`` メソッドを使用できます。これらの特別なコンテキストファイルシステムについて知る必要があるモジュールにアクセスするには、``AnsibleModule`` をインスタンス化し、:attr:`AnsibleModule._selinux_special_fs` でリストを調べます。

en: This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from :ref:`module_replacer`. In module replacer it was a comma separated string of filesystem names. Under Ansiballz it's an actual list.
ja: これにより、:ref:`module_replacer` の :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` を置き換えます。モジュール置換は、ファイル名のコンマ区切りの文字列でした。Ansiballz は、実際のリストになります。

en: This parameter controls which syslog facility Ansible module logs to. To set, change the ``syslog_facility`` value in :file:`ansible.cfg`. Most modules should just use :meth:`AnsibleModule.log` which will then make use of this. If a module has to use this on its own, it should instantiate an `AnsibleModule` and then retrieve the name of the syslog facility from :attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than the old :ref:`module_replacer` code:
ja: このパラメーターは、Ansible モジュールがどの syslog 機能にログを記録するかを制御します。設定するには、:file:`ansible.cfg` の ``syslog_facility`` の値を変更します。多くのモジュールは、これを利用する :meth:`AnsibleModule.log` のみを使用する必要があります。モジュールが独自にこれを使用する必要がある場合は、`AnsibleModule` をインスタンス化して、:attr:`AnsibleModule._syslog_facility` から syslog 機能の名前を取得する必要があります。Ansiballz コードは古い :ref:`module_replacer` コードよりもハッキングされません。

en: This parameter passes the version of Ansible that runs the module. To access it, a module should instantiate an `AnsibleModule` and then retrieve it from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`.
ja: このパラメーターは、モジュールを実行する Ansible のバージョンを渡します。これにアクセスするために、モジュールは `AnsibleModule` をインスタンス化し、:attr:`AnsibleModule.ansible_version` から取得する必要があります。これは、:ref:`module_replacer` の :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` を置き換えます。

en: Module return values & Unsafe strings
ja: モジュール戻り値と安全でない文字列

en: At the end of a module's execution, it formats the data that it wants to return as a JSON string and prints the string to its stdout. The normal action plugin receives the JSON string, parses it into a Python dictionary, and returns it to the executor.
ja: モジュールの実行の最後に、返したいデータを JSON 文字列として形式化し、その文字列を標準出力 (stdout) に出力します。通常の action プラグインは JSON 文字列を受け取り、Python ディクショナリーに解析してエクゼキューターに返します。

en: If Ansible templated every string return value, it would be vulnerable to an attack from users with access to managed nodes. If an unscrupulous user disguised malicious code as Ansible return value strings, and if those strings were then templated on the controller, Ansible could execute arbitrary code. To prevent this scenario, Ansible marks all strings inside returned data as ``Unsafe``, emitting any Jinja2 templates in the strings verbatim, not expanded by Jinja2.
ja: Ansible がすべての文字列の戻り値をテンプレート化すると、管理ノードにアクセスできるユーザーからの攻撃に対して脆弱になります。悪意のあるユーザーが悪意のあるコードを Ansible の戻り値の文字列として偽装し、そのような文字列がコントローラー上でテンプレート化されると、Ansible が任意のコードを実行する可能性があります。このシナリオを防ぐために、Ansible は戻り値のデータ内のすべての文字列を ``Unsafe`` と表示し、文字列内の Jinja2 テンプレートを Jinja2 で展開せずにそのままエミットします。

en: Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automatically marked as ``Unsafe`` by the normal action plugin. If another action plugin retrieves information from a module through some other means, it must mark its return data as ``Unsafe`` on its own.
ja: ``ActionPlugin._execute_module()`` を介してモジュールを呼び出して返された文字列には、通常の action プラグインによって自動的に ``Unsafe`` というマークが付きます。別の action プラグインが他の方法でモジュールから情報を取得した場合は、その action プラグイン自身がその戻り値に ``Unsafe`` と表示する必要があります。

en: In case a poorly-coded action plugin fails to mark its results as "Unsafe," Ansible audits the results again when they are returned to the executor, marking all strings as ``Unsafe``. The normal action plugin protects itself and any other code that it calls with the result data as a parameter. The check inside the executor protects the output of all other action plugins, ensuring that subsequent tasks run by Ansible will not template anything from those results either.
ja: 不適切にコーディングされた action プラグインが結果を「Unsafe」と表示しなかった場合、Ansible はエグゼキューターに返される際に結果を再度監査し、すべての文字列を ``Unsafe`` と表示します。通常の action プラグインは、自身と、結果データをパラメーターとして呼び出すその他のコードを保護します。エクゼキュータ内のチェックは、他のすべての action プラグインの出力を保護し、Ansible が実行する後続のタスクがこれらの結果から何かをテンプレート化することがないようにします。

en: Special considerations
ja: 特別な考慮事項

en: Pipelining
ja: パイプライン

en: Ansible can transfer a module to a remote machine in one of two ways:
ja: Ansible は、以下のいずれかの方法で、モジュールをリモートマシンに転送できます。

en: it can write out the module to a temporary file on the remote host and then use a second connection to the remote host to execute it with the interpreter that the module needs
ja: これは、リモートホストの一時ファイルにモジュールを書き込むことができ、次にリモートホストへの 2 番目の接続を使用して、モジュールが必要とするインタープリターでこれを実行します。

en: or it can use what's known as pipelining to execute the module by piping it into the remote interpreter's stdin.
ja: または、パイプラインと呼ばれるものを使用して、モジュールをリモートインタープリターの stdin にパイプすることでモジュールを実行できます。

en: Pipelining only works with modules written in Python at this time because Ansible only knows that Python supports this mode of operation. Supporting pipelining means that whatever format the module payload takes before being sent over the wire must be executable by Python via stdin.
ja: パイプライン処理は、現時点では Python で記述されたモジュールでのみ機能します。これは、Python がこの操作モードをサポートしていることのみを Ansible が認識しているためです。パイプライン化をサポートするということは、モジュールペイロードがネットワーク経由で送信される前に取る形式が何であれ、Python が stdin を介して実行可能でなければならないことを意味します。

en: Why pass args over stdin?
ja: 標準入力 (stdin) で引数を渡す理由

en: Passing arguments via stdin was chosen for the following reasons:
ja: 以下の理由により、標準入力で引数を渡すことが選択されました。

en: When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from temporarily being saved onto disk on the remote machine. This makes it harder (but not impossible) for a malicious user on the remote machine to steal any sensitive information that may be present in the arguments.
ja: :ref:`ANSIBLE_PIPELINING` と組み合わせると、モジュールの引数をリモートマシン上のディスクに一時的に保存したままにします。これにより、リモートマシン上の悪意のあるユーザーが引数に存在する可能性のある機密情報を盗むのが困難になります (不可能ではありません)。

en: Command line arguments would be insecure as most systems allow unprivileged users to read the full commandline of a process.
ja: ほとんどのシステムでは、権限のないユーザーがプロセスのコマンドライン全体を読むことを許可されているため、コマンドライン引数は安全ではありません。

en: Environment variables are usually more secure than the commandline but some systems limit the total size of the environment. This could lead to truncation of the parameters if we hit that limit.
ja: 環境変数は通常コマンドラインより安全ですが、環境の合計サイズを制限するシステムもあります。これにより、パラメーターが上限に達すると、パラメーターが切り捨てられる可能性があります。

en: Argument spec
ja: 引数の仕様

en: The ``argument_spec`` provided to ``AnsibleModule`` defines the supported arguments for a module, as well as their type, defaults and more.
ja: ``AnsibleModule`` に提供される ``argument_spec`` は、モジュールでサポートされる引数、その型、デフォルトなどを定義します。

en: Example ``argument_spec``:
ja: ``argument_spec`` の例:

en: This section will discuss the behavioral attributes for arguments:
ja: 本セクションでは、引数の動作属性を説明します。

en: ``type`` allows you to define the type of the value accepted for the argument. The default value for ``type`` is ``str``. Possible values are:
ja: ``type`` では、引数に受け入れられる値の型を定義できます。``type`` のデフォルト値は ``str`` です。可能な値は次のとおりです。

en: The ``raw`` type, performs no type validation or type casting, and maintains the type of the passed value.
ja: ``raw`` 型で、型の検証や型キャストを行わず、渡された値の型を保持します。

en: ``elements`` works in combination with ``type`` when ``type='list'``. ``elements`` can then be defined as ``elements='int'`` or any other type, indicating that each element of the specified list should be of that type.
ja: ``elements`` は、``type='list'`` の時に ``type`` と組み合わせて動作します。``elements`` は ``elements='int'`` などの型で定義することができ、指定されたリストの各要素がその型であることを示します。

en: The ``default`` option allows sets a default value for the argument for the scenario when the argument is not provided to the module. When not specified, the default value is ``None``.
ja: ``default`` オプションは、引数がモジュールに提供されていない場合のシナリオの引数のデフォルト値を設定します。指定しない場合、デフォルト値は ``None`` です。

en: ``fallback`` accepts a ``tuple`` where the first argument is a callable (function) that will be used to perform the lookup, based on the second argument. The second argument is a list of values to be accepted by the callable.
ja: ``fallback`` は、第 1 引数に、第 2 引数に基づいて検索を実行するのに使用する callable (関数) の ``tuple`` を受け入れます。2 つ目の引数は、callable オブジェクトによって受け入れられる値のリストです。

en: The most common callable used is ``env_fallback`` which will allow an argument to optionally use an environment variable when the argument is not supplied.
ja: 最も一般的に使用されている callable は ``env_fallback`` で、これは引数が設定されていない場合に任意で環境変数を使用できるようにします。

en: ``choices`` accepts a list of choices that the argument will accept. The types of ``choices`` should match the ``type``.
ja: ``choices`` は、引数が受け入れる選択肢のリストを受け入れます。``choices`` の型は、``type`` と一致している必要があります。

en: ``required`` accepts a boolean, either ``True`` or ``False`` that indicates that the argument is required. When not specified, ``required`` defaults to ``False``. This should not be used in combination with ``default``.
ja: ``required`` ブール値 (``True`` または ``False`` のいずれか) も受け入れます。これは、引数が必要であることを示しています。指定しない場合、``required`` のデフォルトは ``False`` になります。これは、``default`` と組み合わせて使用しないでください。

en: ``no_log`` accepts a boolean, either ``True`` or ``False``, that indicates explicitly whether or not the argument value should be masked in logs and output.
ja: ``no_log`` には、引数の値がログや出力でマスクされるべきかどうかを明示的に示すブール値 (``True`` または ``False``) を使用できます。

en: In the absence of ``no_log``, if the parameter name appears to indicate that the argument value is a password or passphrase (such as "admin_password"), a warning will be shown and the value will be masked in logs but **not** output. To disable the warning and masking for parameters that do not contain sensitive information, set ``no_log`` to ``False``.
ja: ``no_log`` がない場合は、パラメーター名が、引数の値がパスワードやパスフレーズであることを示しているように見える場合 (「admin_password」など)、警告が表示され、値はログでマスクされますが、**出力されません**。機密情報を含まないパラメーターの警告とマスキングを無効にするには、``no_log`` を ``False`` に設定します。

en: ``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name``
ja: ``aliases`` では、引数の代替引数名のリストが使用できます。たとえば、引数が ``name`` ですが、モジュールが ``aliases=['pkg']`` を受け付けて、``pkg`` を ``name`` と互換性を持たせるようにしています。

en: ``options`` implements the ability to create a sub-argument_spec, where the sub options of the top level argument are also validated using the attributes discussed in this section. The example at the top of this section demonstrates use of ``options``. ``type`` or ``elements`` should be ``dict`` is this case.
ja: ``options`` は、上位レベルの引数のサブオプションもこのセクションで説明した属性を使用して検証される sub-argument_spec を作成する機能を実装しています。このセクションの冒頭にある例は、``options`` の使用を示しています。ここでは、``type`` または ``elements`` は ``dict`` である必要があります。

en: ``apply_defaults`` works alongside ``options`` and allows the ``default`` of the sub-options to be applied even when the top-level argument is not supplied.
ja: ``apply_defaults`` は、``options`` と並んで動作し、上位レベルの引数が指定されていない場合でもサブオプションの ``デフォルト`` を適用できるようにします。

en: In the example of the ``argument_spec`` at the top of this section, it would allow ``module.params['top_level']['second_level']`` to be defined, even if the user does not provide ``top_level`` when calling the module.
ja: このセクションの冒頭にある ``argument_spec`` の例では、ユーザーがモジュールを呼び出すときに ``top_level`` を指定しなかった場合でも、``module.params['top_level']['second_level']`` を定義できるようにします。

en: ``removed_in_version`` indicates which version of ansible-core or a collection a deprecated argument will be removed in. Mutually exclusive with ``removed_at_date``, and must be used with ``removed_from_collection``.
ja: ``removed_in_version`` は、非推奨の引数が削除される ansible-core またはコレクションのバージョンを示します。``removed_at_date`` で相互排他され、``removed_from_collection`` で使用する必要があります。

en: ``removed_at_date`` indicates that a deprecated argument will be removed in a minor ansible-core release or major collection release after this date. Mutually exclusive with ``removed_in_version``, and must be used with ``removed_from_collection``.
ja: ``removed_at_date`` は、非推奨の引数が、この日付以降のマイナーな ansible-core リリースまたはメジャーコレクションリリースで削除されることを示します。``removed_in_version`` と相互に排他的であり、``removed_from_collection`` と一緒に使用する必要があります。

en: Specifies which collection (or ansible-core) deprecates this deprecated argument. Specify ``ansible.builtin`` for ansible-core, or the collection's name (format ``foo.bar``). Must be used with ``removed_in_version`` or ``removed_at_date``.
ja: この非推奨の引数を非推奨にするコレクション (または ansible-core) を指定します。ansible-core には ``ansible.builtin``、またはコレクションの名前 (``foo.bar`` の形式) を指定します。``removed_in_version`` または ``removed_at_date`` と共に使用する必要があります。

en: Deprecates aliases of this argument. Must contain a list or tuple of dictionaries having some the following keys:
ja: この引数のエイリアスを非推奨にします。以下のキーを持つディクショナリーのリストまたはタプルが含まれます。

en: The name of the alias to deprecate. (Required.)
ja: 非推奨にするエイリアスの名前 (必須)

en: The version of ansible-core or the collection this alias will be removed in. Either ``version`` or ``date`` must be specified.
ja: ansible-core、またはこのエイリアスは削除されるコレクションのバージョン。``version`` または ``date`` のいずれかを指定する必要があります。

en: The a date after which a minor release of ansible-core or a major collection release will no longer contain this alias.. Either ``version`` or ``date`` must be specified.
ja: ansible-core のマイナーリリースまたはメジャーコレクションリリースにこのエイリアスが含まれなくなった日付。``version`` または ``date`` のいずれかを指定する必要があります。

en: Specifies which collection (or ansible-core) deprecates this deprecated alias. Specify ``ansible.builtin`` for ansible-core, or the collection's name (format ``foo.bar``). Must be used with ``version`` or ``date``.
ja: この非推奨のエイリアスを非推奨にするコレクション (または ansible-core) を指定します。ansible-core には ``ansible.builtin``、またはコレクションの名前 (``foo.bar`` の形式) を指定します。``version`` または ``date`` と共に使用する必要があります。

en: Examples:
ja: 例:

en: If ``options`` is specified, ``mutually_exclusive`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
ja: ``options`` を指定すると、``mutually_exclusive`` は ``options`` で説明されているサブオプションを参照し、:ref:`argument_spec_dependencies` のように動作します。

en: If ``options`` is specified, ``required_together`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
ja: ``options`` を指定すると、``required_together`` は ``options`` で説明されているサブオプションを参照し、:ref:`argument_spec_dependencies` のように動作します。

en: If ``options`` is specified, ``required_one_of`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
ja: ``options`` を指定すると、``required_one_of`` は ``options`` で説明されているサブオプションを参照し、:ref:`argument_spec_dependencies` のように動作します。

en: If ``options`` is specified, ``required_if`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
ja: ``options`` を指定すると、``required_if`` は ``options`` で説明されているサブオプションを参照し、:ref:`argument_spec_dependencies` のように動作します。

en: If ``options`` is specified, ``required_by`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
ja: ``options`` を指定すると、``required_by`` は ``options`` で説明されているサブオプションを参照し、:ref:`argument_spec_dependencies` のように動作します。

en: Dependencies between module options
ja: モジュールオプションの依存関係

en: The following are optional arguments for ``AnsibleModule()``:
ja: 以下は、``AnsibleModule()`` の任意の引数です。

en: Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are mutually exclusive. If more than one options of a list are specified together, Ansible will fail the module with an error.
ja: 文字列シーケンスのシーケンス (リストまたはタプル) です。文字列のシーケンスは相互排他的なオプション名のリストです。リストの複数のオプションを指定すると、Ansible はエラーを出してモジュールに失敗します。

en: In this example, the options ``path`` and ``content`` must not specified at the same time. Also the options ``repository_url`` and ``repository_filename`` must not be specified at the same time. But specifying ``path`` and ``repository_url`` is accepted.
ja: この例では、``path`` オプションと ``content`` オプションは同時に指定しないでください。``repository_url`` オプションと ``repository_filename`` オプションを同時に指定することはできません。ただし、``path`` および ``repository_url`` を指定することはできます。

en: To ensure that precisely one of two (or more) options is specified, combine ``mutually_exclusive`` with ``required_one_of``.
ja: 正確に 2 つのオプション (または複数の) オプションのいずれかを指定するようにするには、``mutually_exclusive`` と ``required_one_of`` を組み合わせます。

en: Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are must be specified together. If at least one of these options are specified, the other ones from the same sequence must all be present.
ja: 文字列のシーケンスのシーケンス (リストまたはタプル) である必要があります。文字列のすべてのシーケンスは、一緒に指定する必要があるオプション名のリストです。これらのオプションが少なくとも 1 つ指定されている場合は、同じシーケンスの他のオプションがすべて存在している必要があります。

en: In this example, if one of the options ``file_path`` or ``file_hash`` is specified, Ansible will fail the module with an error if the other one is not specified.
ja: この例では、``file_path`` または ``file_hash`` のいずれかのオプションを指定し、他のオプションが指定していないと、Ansible はエラーを出してモジュールに失敗します。

en: Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names from which at least one must be specified. If none one of these options are specified, Ansible will fail module execution.
ja: 文字列のシーケンスのシーケンス (リストまたはタプル) である必要があります。文字列のすべてのシーケンスは、少なくとも 1 つを指定する必要があるオプション名のリストです。これらのオプションがいずれも指定されていない場合、Ansible はモジュールの実行に失敗します。

en: In this example, at least one of ``path`` and ``content`` must be specified. If none are specified, execution will fail. Specifying both is explicitly allowed; to prevent this, combine ``required_one_of`` with ``mutually_exclusive``.
ja: この例では、``path`` および ``content`` のいずれかを指定する必要があります。指定しないと、実行が失敗します。両方の値を指定すると、明示的に許可されます。これを回避するには、``required_one_of`` と ``mutually_exclusive`` を組み合わせます。

en: Must be a sequence of sequences. Every inner sequence describes one conditional dependency. Every sequence must have three or four values. The first two values are the option's name and the option's value which describes the condition. The further elements of the sequence are only needed if the option of that name has precisely this value.
ja: 一連のシーケンスのシーケンスである必要があります。すべての内部シーケンスでは、条件の依存関係を 1 つ説明します。すべてのシーケンスには、値が 3 つまたは 4 つ必要です。最初の 2 つの値は、オプション名と、その条件を説明するオプションの値です。シーケンスの追加要素は、その名前のオプションが正確にこの値を持っている場合にのみ必要です。

en: If you want that all options in a list of option names are specified if the condition is met, use one of the following forms:
ja: 条件が満たされた場合にオプション名のリスト内のオプションをすべて指定する場合は、次のいずれかの形式を使用します。

en: If you want that at least one option of a list of option names is specified if the condition is met, use the following form:
ja: 条件が満たされた場合にオプション名の一覧のオプションを 1 つ以上指定する場合は、以下の形式を使用します。

en: In this example, if the user specifies ``state=present``, at least one of the options ``path`` and ``content`` must be supplied (or both). To make sure that precisely one can be specified, combine ``required_if`` with ``mutually_exclusive``.
ja: この例では、ユーザーが ``state=present`` を指定している場合は、``path`` と ``content`` のいずれか (または両方) のオプションを指定する必要があります。必ず指定するようにするには、``required_if`` と ``mutually_exclusive`` を組み合わせます。

en: On the other hand, if ``force`` (a boolean parameter) is set to ``true``, ``yes`` etc., both ``force_reason`` and ``force_code`` must be specified.
ja: 一方、``force`` (ブール値パラメーター) が ``true``、``yes`` などに設定されている場合は、``force_reason`` と ``force_code`` の両方を指定する必要があります。

en: Must be a dictionary mapping option names to sequences of option names. If the option name in a dictionary key is specified, the option names it maps to must all also be specified. Note that instead of a sequence of option names, you can also specify one single option name.
ja: オプション名のシーケンスへのディクショナリーマッピングオプション名である必要があります。ディクショナリーキーでオプション名を指定すると、そのオプション名をすべて指定する必要があります。オプション名のシーケンスの代わりに、オプションの名前を 1 つ指定することもできます。

en: In the example, if ``force`` is specified, ``force_reason`` must also be specified. Also, if ``path`` is specified, then three three options ``mode``, ``owner`` and ``group`` also must be specified.
ja: この例では、``force`` が指定されている場合は、``force_reason`` も指定する必要があります。また、``path`` が指定されている場合は、3 つのオプション ``mode``、``owner``、および ``group`` も指定する必要があります。

en: Declaring check mode support
ja: チェックモードのサポートの宣言

en: To declare that a module supports check mode, supply ``supports_check_mode=True`` to the ``AnsibleModule()`` call:
ja: モジュールが確認モードをサポートすることを宣言するには、``AnsibleModule()`` 呼び出しに ``supports_check_mode=True`` を指定します。

en: The module can determine whether it is called in check mode by checking the boolean value ``module.check_mode``. If it evaluates to ``True``, the module must take care not to do any modification.
ja: モジュールは、ブール値 ``module.check_mode`` を確認することで、チェックモードで呼び出されるかどうかを判断できます。``True`` に評価する場合、モジュールは変更を行わないようにする必要があります。

en: If ``supports_check_mode=False`` is specified, which is the default value, the module will exit in check mode with ``skipped=True`` and message ``remote module (<insert module name here>) does not support check mode``.
ja: ``supports_check_mode=False`` が指定されている場合 (デフォルト値)、モジュールはチェックモードで ``skipped=True`` および ``remote module (<insert module name here>) does not support check mode`` メッセージで終了します。

en: Adding file options
ja: ファイルオプションの追加

en: To declare that a module should add support for all common file options, supply ``add_file_common_args=True`` to the ``AnsibleModule()`` call:
ja: モジュールがすべての共通ファイルオプションのサポートを追加することを宣言するには、``add_file_common_args=True`` を ``AnsibleModule()`` 呼び出しに指定します。

en: You can find `a list of all file options here <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/files.py>`_. It is recommended that you make your ``DOCUMENTATION`` extend the doc fragment ``ansible.builtin.files`` (see :ref:`module_docs_fragments`) in this case, to make sure that all these fields are correctly documented.
ja: `a list of all file options here <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/files.py>`_ を確認できます。今回は、``DOCUMENTATION`` がドキュメントフラグメント ``ansible.builtin.files`` (:ref:`module_docs_fragments`を参照) を拡張し、これらのフィールドがすべて正しく文書化されていることを確認することが推奨されます。

en: The helper functions ``module.load_file_common_arguments()`` and ``module.set_fs_attributes_if_different()`` can be used to handle these arguments for you:
ja: ヘルパー関数 ``module.load_file_common_arguments()`` および ``module.set_fs_attributes_if_different()`` を使用して、以下の引数を扱うことができます。

en: Ansible and Python 3
ja: Ansible および Python 3

en: The ``ansible-core`` code runs on both Python 2 and Python 3 because we want Ansible to be able to manage a wide variety of machines. Contributors to ansible-core and to Ansible Collections should be aware of the tips in this document so that they can write code that will run on the same versions of Python as the rest of Ansible.
ja: Ansible が各種マシンを管理できるようにするため、``ansible-core`` コードは Python 2 と Python 3 の両方で実行されます。ansible-core と Ansible Collections に貢献する場合は、このドキュメントのヒントを確認して、Ansible の残りの部分と同じバージョンの Python で実行するコードを記述できるようにする必要があります。

en: To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks and idioms described here. Most of these considerations apply to all three types of Ansible code:
ja: Python 2 および Python 3 でコードが実行されるようにするには、ここで説明するヒントとコツ、およびイディオムを確認してください。これらの考慮事項は、これら 3 種類の Ansible コードのすべてに適用されます。

en: controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible`
ja: コントローラー側のコード: :command:`/usr/bin/ansible` を呼び出すマシンで実行されるコード

en: modules - the code which Ansible transmits to and invokes on the managed machine.
ja: モジュール - 管理マシンに Ansible が送信したり起動したりするコード。

en: shared ``module_utils`` code - the common code that's used by modules to perform tasks and sometimes used by controller-side code as well
ja: 共有されている ``module_utils`` コード - タスクを実行するためにモジュールが使用する一般的なコードで、コントローラーのコードでも使用されることがあります。

en: However, the three types of code do not use the same string strategy. If you're developing a module or some ``module_utils`` code, be sure to read the section on string strategy carefully.
ja: ただし、この 3 種類のコードで同じ文字列戦略が使用されているわけではありません。モジュールまたはいくつかの ``module_utils`` コードを開発している場合は、文字列戦略のセクションを注意してお読みください。

en: Minimum version of Python 3.x and Python 2.x
ja: Python 3.x および Python 2.x の最小バージョン

en: On the controller we support Python 3.5 or greater and Python 2.7 or greater.  Module-side, we support Python 3.5 or greater and Python 2.6 or greater.
ja: コントローラーでは、Python 3.5 以降、および Python 2.7 以降をサポートしています。モジュール側では、Python 3.5 以降、Python 2.6 以降をサポートします。

en: Python 3.5 was chosen as a minimum because it is the earliest Python 3 version adopted as the default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04). Previous LTS Linux distributions shipped with a Python 2 version which users can rely upon instead of the Python 3 version.
ja: Python 3.5 は、長期サポート (LTS: Long Term Support) の Linux ディストリビューション (この場合は Ubuntu-16.04) でデフォルトの Python として採用されている最も古い Python 3 のバージョンであるため、最小バージョンとして採用されました。以前の LTS Linux ディストリビューションでは、Python 3 バージョンの代わりに、ユーザーが代わりに使用できる Python 2 バージョンが同梱されていました。

en: For Python 2, the default is for modules to run on at least Python 2.6.  This allows users with older distributions that are stuck on Python 2.6 to manage their machines.  Modules are allowed to drop support for Python 2.6 when one of their dependent libraries requires a higher version of Python. This is not an invitation to add unnecessary dependent libraries in order to force your module to be usable only with a newer version of Python; instead it is an acknowledgment that some libraries (for instance, boto3 and docker-py) will only function with a newer version of Python.
ja: Python 2 では、モジュールは少なくとも Python 2.6 で動作することがデフォルトとなっています。これにより、Python 2.6 に固執する古いディストリビューションのユーザーが自分のマシンを管理できるようになります。モジュールは、依存するライブラリーの 1 つがより高いバージョンの Python を必要とする場合は、Python 2.6 のサポートを終了することができます。これは、自作したモジュールを、より新しいバージョンの Python でしか使えないようにするために、不要な依存ライブラリーを追加することを勧めるものではありません。代わりに、いくつかのライブラリー (例えば、boto3 や docker-py) はより新しいバージョンの Python でしか機能しないことを承認します。

en: Python 2.4 Module-side Support:
ja: Python 2.4 モジュールでのサポート:

en: Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4.  RHEL-5 (and its rebuilds like CentOS-5) were supported until April of 2017. Ansible-2.3 was released in April of 2017 and was the last Ansible release to support Python 2.4 on the module-side.
ja: Python 2.4 および Python 2.5 のサポートは Ansible-2.4 から削除されました。RHEL-5 (および CentOS-5) は 2017 年 4 月までサポートされます。Ansible-2.3 は 2017 年 4 月にリリースされ、これがモジュールサイドの Python 2.4 をサポートする最後の Ansible リリースでした。

en: Developing Ansible code that supports Python 2 and Python 3
ja: Python 2 および Python 3 をサポートする Ansible コードの開発

en: The best place to start learning about writing code that supports both Python 2 and Python 3 is `Lennart Regebro's book: Porting to Python 3 <http://python3porting.com/>`_. The book describes several strategies for porting to Python 3. The one we're using is `to support Python 2 and Python 3 from a single code base <http://python3porting.com/strategies.html#python-2-and-python-3-without-conversion>`_
ja: Python 2 と Python 3 の両方をサポートするコードの記述について学び始めるのに最適なのは、`Lennart Regebro の著書: Porting to Python 3 <http://python3porting.com/>`_ です。本書では、Python 3 に移植するためのいくつかの戦略が説明されています。Ansible で使用しているのは、`単一のコードベースから Python 2 および Python 3 をサポートするため <http://python3porting.com/strategies.html#python-2-and-python-3-without-conversion>`_ です。

en: Understanding strings in Python 2 and Python 3
ja: Python 2 および Python 3 の文字列を理解

en: Python 2 and Python 3 handle strings differently, so when you write code that supports Python 3 you must decide what string model to use.  Strings can be an array of bytes (like in C) or they can be an array of text.  Text is what we think of as letters, digits, numbers, other printable symbols, and a small number of unprintable "symbols" (control codes).
ja: Python 2 と Python 3 では文字列の扱いが異なるため、Python 3 をサポートするコードを作成するときは、どのような文字列モデルを使用するかを決める必要があります。文字列は (C 言語のように) バイトの配列にすることもできますし、テキストの配列にすることもできます。ここでの「テキスト」とは、文字、数字 (digit または number)、その他の印刷可能な記号、および少数の印刷不可能な「記号」(制御コード) になります。

en: In Python 2, the two types for these (:class:`str <python:str>` for bytes and :func:`unicode <python:unicode>` for text) are often used interchangeably.  When dealing only with ASCII characters, the strings can be combined, compared, and converted from one type to another automatically.  When non-ASCII characters are introduced, Python 2 starts throwing exceptions due to not knowing what encoding the non-ASCII characters should be in.
ja: Python 2 では、これらの 2 つのタイプ (バイト単位の場合は :class:`str <python:str>`、テキストの場合は :func:`unicode <python:unicode>`) が、しばしば同じ意味で使用されます。ASCII 文字のみを処理する場合は、文字列を組み合わせて比較し、あるタイプから別のタイプに自動的に変換できます。非 ASCII 文字が導入されると、Python 2 は、非 ASCII 文字がどのエンコーディングに含まれるべきかわからないために例外を出力し始めます。

en: Python 3 changes this behavior by making the separation between bytes (:class:`bytes <python3:bytes>`) and text (:class:`str <python3:str>`) more strict.  Python 3 will throw an exception when trying to combine and compare the two types.  The programmer has to explicitly convert from one type to the other to mix values from each.
ja: Python 3 は、バイト (:class:`bytes <python3:bytes>`) とテキスト (:class:`str <python3:str>`) を分離することでこの動作を変更します。Python 3 は 2 つのタイプの結合と比較を試みる際に例外を出力させます。プログラマーは、ある型から別の型に変換し、混在させる必要があります。

en: In Python 3 it's immediately apparent to the programmer when code is mixing the byte and text types inappropriately, whereas in Python 2, code that mixes those types may work until a user causes an exception by entering non-ASCII input. Python 3 forces programmers to proactively define a strategy for working with strings in their program so that they don't mix text and byte strings unintentionally.
ja: Python 3 では、プログラマーは、コードがバイト型とテキスト型を不適切に混合していることがすぐに分かりますが、Python 2 では、ユーザーが非 ASCII 入力を入力して例外が発生するまでは、これらの型を混合しているコードが動作するかもしれません。Python 3 では、プログラマーが意図せずにテキスト文字列とバイト文字列を混在させないように、プログラムの中で文字列を扱うためのストラテジーを積極的に定義することを強制しています。

en: Ansible uses different strategies for working with strings in controller-side code, in :ref: `modules <module_string_strategy>`, and in :ref:`module_utils <module_utils_string_strategy>` code.
ja: Ansible は、:ref:`modules <module_string_strategy>` コードおよび :ref:`module_utils <module_utils_string_strategy>` コードのコントローラー側のコードで文字列を操作するためにさまざまなストラテジーを使用します。

en: Controller string strategy: the Unicode Sandwich
ja: コントローラー文字列ストラテジー: Unicode Sandwich

en: In controller-side code we use a strategy known as the Unicode Sandwich (named after Python 2's :func:`unicode  <python:unicode>` text type).  For Unicode Sandwich we know that at the border of our code and the outside world (for example, file and network IO, environment variables, and some library calls) we are going to receive bytes. We need to transform these bytes into text and use that throughout the internal portions of our code.  When we have to send those strings back out to the outside world we first convert the text back into bytes. To visualize this, imagine a 'sandwich' consisting of a top and bottom layer of bytes, a layer of conversion between, and all text type in the center.
ja: コントローラー側のコードでは、Unicode Sandwich と呼ばれるストラテジーを使用します (名前は Python 2 の :func:`unicode  <python:unicode>` テキストタイプに由来します)。Unicode Sandwich の場合、コードと外部の境界 (ファイルやネットワークの IO、環境変数、ライブラリーの呼び出しなど) でバイトを受信することがわかります。これらのバイトをテキストに変換し、コードの内部全体でこれを使用する必要があります。これらの文字列を外部に返す必要がある場合は、最初にテキストをバイトに変換します。これは、上下にバイトの層、その間に変換の層、その中央にあるすべてのテキストタイプからなる「サンドイッチ」を想像してください。

en: Unicode Sandwich common borders: places to convert bytes to text in controller code
ja: Unicode Sandwich の共通の境界: コントローラーコードのテキストにバイトを変換する場所

en: This is a partial list of places where we have to convert to and from bytes when using the Unicode Sandwich string strategy. It's not exhaustive but it gives you an idea of where to watch for problems.
ja: これは、Unicode Sandwich 文字列ストラテジーの使用時に、バイトへ、またはバイトから変換する場所の部分的なリストです。網羅的ではありませんが、問題を監視する場所がわかります。

en: Reading and writing to files
ja: ファイルの読み取りおよび書き込み

en: In Python 2, reading from files yields bytes.  In Python 3, it can yield text. To make code that's portable to both we don't make use of Python 3's ability to yield text but instead do the conversion explicitly ourselves. For example:
ja: Python 2 では、ファイルから読み取るとバイトが生成されます。Python 3 では、テキストを生成できます。両方に移植可能なコードを作成するために、Python 3 のテキスト生成機能を利用せず、代わりに自身で明示的に変換を行います。以下に例を示します。

en: Much of Ansible assumes that all encoded text is UTF-8.  At some point, if there is demand for other encodings we may change that, but for now it is safe to assume that bytes are UTF-8.
ja: Ansible の多くは、エンコードされたテキストがすべて UTF-8 であることを前提としています。将来変更することがあるかもしれませんが、現時点では、バイトが UTF-8 であると考えて問題ありません。

en: Writing to files is the opposite process:
ja: ファイルへの書き込みは、その逆の処理です。

en: Note that we don't have to catch :exc:`UnicodeError` here because we're transforming to UTF-8 and all text strings in Python can be transformed back to UTF-8.
ja: UTF-8 に変換していて、Python のテスト文字列がすべて UTF-8 に戻されるため、ここで :exc:`UnicodeError` を取得する必要がないことに注意してください。

en: Filesystem interaction
ja: ファイルシステムの相互作用

en: Dealing with filenames often involves dropping back to bytes because on UNIX-like systems filenames are bytes.  On Python 2, if we pass a text string to these functions, the text string will be converted to a byte string inside of the function and a traceback will occur if non-ASCII characters are present.  In Python 3, a traceback will only occur if the text string can't be decoded in the current locale, but it's still good to be explicit and have code which works on both versions:
ja: UNIX 系システムではファイル名はバイトであるため、ファイル名を扱う際にはしばしばバイトに戻すことになります。Python 2 では、これらの関数にテキスト文字列を渡すと、テキスト文字列は関数内でバイト文字列に変換され、非 ASCII 文字が存在する場合にはトレースバックが発生します。Python 3 では、トレースバックはテキスト文字列が現在のロケールでデコードできない場合にのみ発生しますが、明示的に両方のバージョンで動作するコードを用意しておくことが推奨されます。

en: When you are only manipulating a filename as a string without talking to the filesystem (or a C library which talks to the filesystem) you can often get away without converting to bytes:
ja: ファイルシステム (またはファイルシステムと通信する C ライブラリー) と通信せずにファイル名を文字列として操作するだけの場合は、バイトに変換する必要がないことがよくあります。

en: On the other hand, if the code needs to manipulate the filename and also talk to the filesystem, it can be more convenient to transform to bytes right away and manipulate in bytes.
ja: 一方、コードがファイル名を操作し、ファイルシステムとやりとりする場合は、すぐにバイトバイトに変換して題と単位で操作する方が便利です。

en: Make sure all variables passed to a function are the same type. If you're working with something like :func:`python3:os.path.join` which takes multiple strings and uses them in combination, you need to make sure that all the types are the same (either all bytes or all text).  Mixing bytes and text will cause tracebacks.
ja: 関数に渡されるすべての変数が同じタイプであることを確認します。:func:`python3:os.path.join` のように、複数の文字列を取得し、これらの変数を組み合わせて使用する場合は、すべてのタイプが同じ (すべてのバイトまたはすべてのテキストのいずれか) になるようにする必要があります。バイトとテキストを混在させると、トレースバックが発生します。

en: Interacting with other programs
ja: 他のプログラムとの相互作用

en: Interacting with other programs goes through the operating system and C libraries and operates on things that the UNIX kernel defines.  These interfaces are all byte-oriented so the Python interface is byte oriented as well.  On both Python 2 and Python 3, byte strings should be given to Python's subprocess library and byte strings should be expected back from it.
ja: 他のプログラムとの対話は、オペレーティングシステムと C ライブラリーを経由して、UNIX カーネルが定義するものを操作します。これらのインターフェースはすべてバイト指向であるため、Python インターフェースもバイト指向です。Python 2 と Python3 の両方で、バイト文字列は Python のサブプロセスライブラリーに渡され、バイト文字列はそこから返されることが期待されます。

en: One of the main places in Ansible's controller code that we interact with other programs is the connection plugins' ``exec_command`` methods.  These methods transform any text strings they receive in the command (and arguments to the command) to execute into bytes and return stdout and stderr as byte strings Higher level functions (like action plugins' ``_low_level_execute_command``) transform the output into text strings.
ja: Ansible のコントローラーコードで他のプログラムとやり取りする主な場所の 1 つは、接続プラグインの ``exec_command`` メソッドです。これらのメソッドは、コマンドで受け取ったテキスト文字列 (およびコマンドへの引数) をバイトに変換し、stdout と stderr をバイト文字列として返します。(アクションプラグインの ``_low_level_execute_command`` のように) 高レベルの関数出力をテキスト文字列に変換します。

en: Module string strategy: Native String
ja: モジュール文字列ストラテジー: ネイティブ文字列

en: In modules we use a strategy known as Native Strings. This makes things easier on the community members who maintain so many of Ansible's modules, by not breaking backwards compatibility by mandating that all strings inside of modules are text and converting between text and bytes at the borders.
ja: モジュールでは、ネイティブ文字列と呼ばれるストラテジーを採用しています。これにより、Ansible の多くのモジュールを保守しているコミュニティーメンバーは、モジュール内のすべての文字列がテキストであることを義務付けたり、境界でテキストとバイトの間を変換したりすることで、後方互換性を壊さないようにしています。

en: Native strings refer to the type that Python uses when you specify a bare string literal:
ja: ネイティブ文字列は、裸の文字列リテラルを指定するときに Python が使用するタイプを参照します。

en: In Python 2, these are byte strings. In Python 3 these are text strings. Modules should be coded to expect bytes on Python 2 and text on Python 3.
ja: Python 2 では、これらはバイト文字列です。Python 3 では、これらはテキスト文字列です。Python 2 ではバイト、および Python 3 ではテキストを期待するようにコード化されている必要があります。

en: Module_utils string strategy: hybrid
ja: Module_utils 文字列ストラテジー: ハイブリッド

en: In ``module_utils`` code we use a hybrid string strategy. Although Ansible's ``module_utils`` code is largely like module code, some pieces of it are used by the controller as well. So it needs to be compatible with modules and with the controller's assumptions, particularly the string strategy. The module_utils code attempts to accept native strings as input to its functions and emit native strings as their output.
ja: ``module_utils`` コードでは、ハイブリッドな文字列ストラテジーを採用します。Ansible の ``module_utils`` コードは、大部分がモジュールコードのようなものですが、その一部はコントローラーでも使用されます。そのため、モジュールやコントローラの前提条件との互換性、特に文字列ストラテジーとの互換性が必要になります。module_utils コードは、その関数への入力としてネイティブ文字列を受け入れ、その出力としてネイティブ文字列を出力しようとします。

en: In ``module_utils`` code:
ja: ``module_utils`` コードの場合:

en: Functions **must** accept string parameters as either text strings or byte strings.
ja: 関数は、文字列パラメーターをテキスト文字列またはバイト文字列のいずれかで使用できるようにする **必要があります**。

en: Functions may return either the same type of string as they were given or the native string type for the Python version they are run on.
ja: 関数は、提供された文字列と同じタイプの文字列を返すか、実行している Python のバージョンに合わせたネイティブの文字列型を返すことができます。

en: Functions that return strings **must** document whether they return strings of the same type as they were given or native strings.
ja: 文字列を返す関数は、指定の文字列と同じ型の文字列を返すのか、ネイティブの文字列を返すのかを文書化する **必要があります**。

en: Module-utils functions are therefore often very defensive in nature. They convert their string parameters into text (using ``ansible.module_utils.common.text.converters.to_text``) at the beginning of the function, do their work, and then convert the return values into the native string type (using ``ansible.module_utils.common.text.converters.to_native``) or back to the string type that their parameters received.
ja: したがって、module_utils 関数は、本質的に非常に防御的であることがよくあります。この関数は、関数の先頭で (``ansible.module_utils.common.text.converters.to_text`` を使用して) 文字列パラメーターをテキストに変換し、作業を行い、(``ansible.module_utils.common.text.converters.to_native`` を使用して) 戻り値をネイティブの文字列型に変換します。または、パラメーターが受け取った文字列型に戻ります。

en: Tips, tricks, and idioms for Python 2/Python 3 compatibility
ja: Python 2/Python 3 互換のためのヒント、トリック、およびイディオム

en: Use forward-compatibility boilerplate
ja: 前方互換性のある boilerplate の使用

en: Use the following boilerplate code at the top of all python files to make certain constructs act the same way on Python 2 and Python 3:
ja: Python 2 と Python 3 で特定の構成要素が同じように動作するようにするために、すべての python ファイルの先頭に以下の boilerplate コードを使用してください。

en: ``__metaclass__ = type`` makes all classes defined in the file into new-style classes without explicitly inheriting from :class:`object <python3:object>`.
ja: ``__metaclass__ = type`` は、ファイルで定義されているすべてのクラスを :class:`object <python3:object>` から明示的に継承することなく、新しいスタイルのクラスにします。

en: The ``__future__`` imports do the following:
ja: ``__future__`` のインポートは以下を行います。

en: Makes imports look in :data:`sys.path <python3:sys.path>` for the modules being imported, skipping the directory in which the module doing the importing lives.  If the code wants to use the directory in which the module doing the importing, there's a new dot notation to do so.
ja: インポートは、インポートされるモジュールの :data:`sys.path <python3:sys.path>` を検索し、インポートを行うモジュールが存在するディレクトリーをスキップします。インポートを行うモジュールが存在するディレクトリーをコードが使用したい場合は、新しいドット表記があります。

en: Makes division of integers always return a float.  If you need to find the quotient use ``x // y`` instead of ``x / y``.
ja: 整数の除算が常に浮動小数点を返すようになります。商を見つける必要がある場合は、``x / y`` の代わりに ``x // y`` を使用してください。

en: Changes :func:`print <python3:print>` from a keyword into a function.
ja: キーワードから関数への :func:`print <python3:print>` の変更

en: Prefix byte strings with ``b_``
ja: バイト文字列のプレフィックス: ``b_``

en: Since mixing text and bytes types leads to tracebacks we want to be clear about what variables hold text and what variables hold bytes.  We do this by prefixing any variable holding bytes with ``b_``.  For instance:
ja: テキスト型とバイト型が混在するとトレースバックが発生するため、どの変数がテキストを保持していて、どの変数がバイトを保持しているかを明確にします。これは、バイトを保持する変数には、``b_`` をプレフィックスとして使用します。以下に例を示します。

en: We do not prefix the text strings instead because we only operate on byte strings at the borders, so there are fewer variables that need bytes than text.
ja: 代わりに、ボーダーのバイト文字列でのみ動作するためテキスト文字列はプレフィックスとして付けられません。したがって、テキスト文字列の前にバイト値が必要な変数が少なくなります。

en: Import Ansible's bundled Python ``six`` library
ja: Ansible のバンドルされた Python ``six`` ライブラリーをインポート

en: The third-party Python `six <https://pypi.org/project/six/>`_ library exists to help projects create code that runs on both Python 2 and Python 3.  Ansible includes a version of the library in module_utils so that other modules can use it without requiring that it is installed on the remote system.  To make use of it, import it like this:
ja: サードパーティーの Python `six <https://pypi.org/project/six/>`_ ライブラリーは、プロジェクトが Python 2 および Python 3 の両方で実行するコードを作成するのに役立ちます。Ansible には、module_utils にライブラリーのバージョンが含まれ、他のモジュールがリモートシステムにインストールされなくても使用可能となるようになっています。これを使用して、以下のようにインポートしてください。

en: Ansible can also use a system copy of six
ja: Ansible は、six のシステムコピーを使用することもできます。

en: Ansible will use a system copy of six if the system copy is a later version than the one Ansible bundles.
ja: Ansible は、システムコピーが、Ansible がバンドルしているものよりも後のバージョンのものであれば、six のシステムコピーを使用します。

en: Handle exceptions with ``as``
ja: ``as`` で例外を処理します。

en: In order for code to function on Python 2.6+ and Python 3, use the new exception-catching syntax which uses the ``as`` keyword:
ja: Python 2.6 以降および Python 3 でコードが機能するには、``as`` キーワードを使用する新しい例外キャッチ構文を使用してください。

en: Do **not** use the following syntax as it will fail on every version of Python 3:
ja: 以下の構文は、Python 3 のすべてのバージョンで失敗するため、**使用しないでください**。

en: Update octal numbers
ja: 8 進数の更新

en: In Python 2.x, octal literals could be specified as ``0755``.  In Python 3, octals must be specified as ``0o755``.
ja: Python 2.x では、8 進数リテラルは ``0755`` と指定できました。Python 3 では、8 進数は ``0o755`` と指定しなければなりません。

en: String formatting for controller code
ja: コントローラーコードの文字列形式

en: Use ``str.format()`` for Python 2.6 compatibility
ja: Python 2.6 の互換性のために ``str.format()`` を使用します。

en: Starting in Python 2.6, strings gained a method called ``format()`` to put strings together.  However, one commonly used feature of ``format()`` wasn't added until Python 2.7, so you need to remember not to use it in Ansible code:
ja: Python 2.6 以降、文字列には、文字列をまとめる ``format()`` という名前のメソッドが追加されました。ただし、``format()`` に一般的に使用される機能の 1 つは Python 2.7 まで追加されなかったため、Ansible コードで使用しないように注意する必要があります。

en: Both of the format strings above map positional arguments of the ``format()`` method into the string.  However, the first version doesn't work in Python 2.6.  Always remember to put numbers into the placeholders so the code is compatible with Python 2.6.
ja: 上記の両方の形式文字列では、``format()`` メソッドの位置引数を文字列にマッピングしますが、最初のバージョンは Python 2.6 では動作しません。常に数字をプレースホルダーに置き、コードが Python 2.6 と互換性を持つようにします。

en: Python documentation on `format strings <https://docs.python.org/2/library/string.html#formatstrings>`_
ja: `フォーマットの文字列 <https://docs.python.org/2/library/string.html#formatstrings>`_ に関する Python ドキュメント

en: Use percent format with byte strings
ja: バイト文字列でのパーセント書式の使用

en: In Python 3.x, byte strings do not have a ``format()`` method.  However, it does have support for the older, percent-formatting.
ja: Python 3.x では、バイト文字列に ``format()`` メソッドがありませんが、以前のパーセント形式をサポートします。

en: Percent formatting added in Python 3.5
ja: Python 3.5 に追加されたパーセント書式

en: Percent formatting of byte strings was added back into Python 3 in 3.5. This isn't a problem for us because Python 3.5 is our minimum version. However, if you happen to be testing Ansible code with Python 3.4 or earlier, you will find that the byte string formatting here won't work. Upgrade to Python 3.5 to test.
ja: Python 3 では、Python 3.5 に、バイト文字列のパーセント書式が追加されました。Python 3.5 は最小バージョンであるため、これは問題ではありません。ただし、Python 3.4 以前のバージョンで Ansible のコードをテストしている場合は、ここでのバイト文字列の書式設定が適切に処理されないことがあります。その場合は、Python 3.5 にアップグレードしてテストしてください。

en: Python documentation on `percent formatting <https://docs.python.org/2/library/stdtypes.html#string-formatting>`_
ja: `パーセンテージフォーマット <https://docs.python.org/2/library/stdtypes.html#string-formatting>`_ に関する Python ドキュメント

en: Testing modules on Python 3
ja: Python 3 でのモジュールのテスト

en: Ansible modules are slightly harder to code to support Python 3 than normal code from other projects. A lot of mocking has to go into unit testing an Ansible module, so it's harder to test that your changes have fixed everything or to to make sure that later commits haven't regressed the Python 3 support. Review our :ref:`testing <developing_testing>` pages for more information.
ja: Ansible モジュールは、その他のプロジェクトの通常のコードよりも Python 3 をサポートするようにコーディングするのが若干難しくなります。多くのモックは、Ansible モジュールのユニットテストに入る必要があるため、変更によってすべてが修正されたことをテストするか、後のコミットが Python 3 をサポートしないようにする方が困難になります。詳細は、:ref:`テスト <developing_testing>` ページを参照してください。

en: Rebasing a pull request
ja: プル要求のリベース

en: You may find that your pull request (PR) is out-of-date and needs to be rebased. This can happen for several reasons:
ja: プル要求 (PR) が古いため、リベースが必要になる場合があります。これにはいくつかの理由が考えられます。

en: Files modified in your PR are in conflict with changes which have already been merged.
ja: 発行する PR で変更されたファイルは、すでにマージされている変更と競合しています。

en: Your PR is old enough that significant changes to automated test infrastructure have occurred.
ja: 発行する PR は、自動化されたテストインフラストラクチャーに大幅な変更が加えられるほど古いものです。

en: Rebasing the branch used to create your PR will resolve both of these issues.
ja: PR を作成するのに使用するブランチを再設定すると、この両方の問題が解決されます。

en: Configuring your remotes
ja: リモートの設定

en: Before you can rebase your PR, you need to make sure you have the proper remotes configured. These instructions apply to any repository on GitHub, including collections repositories. On other platforms (bitbucket, gitlab), the same principles and commands apply but the syntax may be different. We use the ansible/ansible repository here as an example. In other repositories, the branch names may be different. Assuming you cloned your fork in the usual fashion, the ``origin`` remote will point to your fork::
ja: PR をリベースする前に、適切なリモートが設定されていることを確認する必要があります。この手順は、コレクションリポジトリーを含む GitHub のすべてのリポジトリーに適用されます。他のプラットフォーム (bitbucket や gitlab) でも同様の原則とコマンドが適用されますが、構文が異なる場合があります。ここでは、ansible/ansible のリポジトリーを例に挙げています。他のリポジトリーでは、ブランチ名が異なる場合があります。通常の方法でフォークをクローンしたと仮定すると、``origin`` のリモートは操作したユーザーのフォークを指すことになります::

en: However, you also need to add a remote which points to the upstream repository::
ja: ただし、アップストリームのリポジトリーを参照するリモートを追加する必要もあります。

en: Which should leave you with the following remotes::
ja: 次のリモートを残す必要があります。

en: Checking the status of your branch should show your fork is up-to-date with the ``origin`` remote::
ja: ブランチのステータスを確認すると、``origin`` のリモートのフォークが最新の状態であることを理解できます。

en: Rebasing your branch
ja: ブランチのリベース

en: Once you have an ``upstream`` remote configured, you can rebase the branch for your PR::
ja: ``upstream`` のリモートを設定したら、PR のブランチをリベースできます。

en: This will replay the changes in your branch on top of the changes made in the upstream ``devel`` branch. If there are merge conflicts, you will be prompted to resolve those before you can continue.
ja: これにより、アップストリームの ``devel`` ブランチで変更したブランチに変更が再生されます。マージの競合が発生した場合は、続行する前に解決するように求められます。

en: After you rebase, the status of your branch changes::
ja: リベース後に、ブランチのステータスが変更になります。

en: Don't worry, this is normal after a rebase. You should ignore the ``git status`` instructions to use ``git pull``. We'll cover what to do next in the following section.
ja: リベースの後、これは通常通りとなります。``git pull`` を使用する ``git status`` 命令は無視する必要があります。次のセクションでは、次に何をするかについて説明します。

en: Updating your pull request
ja: プル要求の更新

en: Now that you've rebased your branch, you need to push your changes to GitHub to update your PR.
ja: ブランチをリベースしたら、変更を GitHub にプッシュして、PR を更新する必要があります。

en: Since rebasing re-writes git history, you will need to use a force push::
ja: リベースは、git 履歴を再書き込みするため、強制的にプッシュする必要があります。

en: Your PR on GitHub has now been updated. This will automatically trigger testing of your changes. You should check in on the status of your PR after tests have completed to see if further changes are required.
ja: GitHub の PR が更新されました。これにより、変更のテストが自動的に発生します。テスト完了後に PR のステータスを確認し、さらなる変更が必要であるかどうかを確認する必要があります。

en: Getting help rebasing
ja: リベースのヘルプ

en: For help with rebasing your PR, or other development related questions, join us on our #ansible-devel IRC chat channel on `irc.libera.chat <https://libera.chat/>`_.
ja: PR またはその他の開発関連の質問を再設定する際には、`irc.libera.chat <https://libera.chat/>`_ で IRC チャットチャンネル #ansible-devel に参加します。

en: Information on roadmaps, opening PRs, Ansibullbot, and more
ja: ロードマップ、オープン PRS、Ansibullbot などに関する情報

en: Developer Guide
ja: 開発者ガイド

en: **Making Open Source More Inclusive**
ja: **多様性を受け入れるオープンソースの強化**

en: Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see `our CTO Chris Wright's message <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_.
ja: Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。問題のある用語を見つけた場合は、問題を作成するか、プル要求を作成してください。詳細は、`弊社 の CTO、Chris Wright のメッセージ <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_ を参照してください。

en: Welcome to the Ansible Developer Guide!
ja: Ansible 開発者ガイドにようこそ!

en: **Who should use this guide?**
ja: **本ガイドの対象者**

en: If you want to extend Ansible by using a custom module or plugin locally, creating a module or plugin, adding functionality to an existing module, or expanding test coverage, this guide is for you. We've included detailed information for developers on how to test and document modules, as well as the prerequisites for getting your module or plugin accepted into the main Ansible repository.
ja: カスタムモジュールまたはプラグインのローカルでの使用、モジュールまたはプラグインの作成、既存のモジュールへの機能の追加、テスト範囲の拡張を行って Ansible を拡張する場合は、このガイドをご利用になれます。モジュールのテストおよびドキュメント化に関する方法についての開発者向けの詳細情報、および主な Ansible リポジトリーに受け入れられるモジュールまたはプラグインを取得するための前提条件が記載されています。

en: Find the task that best describes what you want to do:
ja: 以下の中から、お客様のニーズに最も適したタスクを選んでください。

en: I'm looking for a way to address a use case:
ja: ユースケースに対応する方法を探している。

en: I want to :ref:`add a custom plugin or module locally <developing_locally>`.
ja: :ref:`カスタムプラグインまたはモジュールをローカルに追加 <developing_locally>` したいです。

en: I want to figure out if :ref:`developing a module is the right approach <module_dev_should_you>` for my use case.
ja: 選択したユースケースでは、:ref:`モジュールの開発が適切なアプローチである <module_dev_should_you>` かどうかを確認したいです。

en: I want to :ref:`develop a collection <developing_collections>`.
ja: :ref:`コレクションを開発 <developing_collections>` したいです。

en: I want to :ref:`contribute to an Ansible-maintained collection <contributing_maintained_collections>`.
ja: :ref:`Ansible が管理するコレクションに貢献 <contributing_maintained_collections>` したいです。

en: I want to :ref:`contribute to a community-maintained collection <hacking_collections>`.
ja: :ref:`コミュニティーが管理するコレクションに貢献 <hacking_collections>` したいです。

en: I want to :ref:`migrate a role to a collection <migrating_roles>`.
ja: :ref:`ロールをコレクションに移行 <migrating_roles>` したいです。

en: I've read the info above, and I'm sure I want to develop a module:
ja: 上記の情報を読んで、モジュールを開発したい。

en: What do I need to know before I start coding?
ja: コーディングを始める前に何を知っておくべきか。

en: I want to :ref:`set up my Python development environment <environment_setup>`.
ja: :ref:`Python 開発環境をセットアップ <environment_setup>` したいです。

en: I want to :ref:`get started writing a module <developing_modules_general>`.
ja: :ref:`モジュールの記述を開始 <developing_modules_general>` したいです。

en: I want to write a specific kind of module:
ja: 特定のモジュールを作成したいです。

en: a :ref:`network module <developing_modules_network>`
ja: :ref:`ネットワークモジュール <developing_modules_network>`

en: a :ref:`Windows module <developing_modules_general_windows>`.
ja: :ref:`Windows モジュール <developing_modules_general_windows>`

en: an :ref:`Amazon module <AWS_module_development>`.
ja: :ref:`Amazon モジュール <AWS_module_development>`

en: an :ref:`OpenStack module <OpenStack_module_development>`.
ja: :ref:`OpenStack モジュール <OpenStack_module_development>`

en: an :ref:`oVirt/RHV module <oVirt_module_development>`.
ja: :ref:`oVirt/RHV モジュール <oVirt_module_development>`

en: a :ref:`VMware module <VMware_module_development>`.
ja: :ref:`VMware モジュール <VMware_module_development>`

en: I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on).
ja: Ansible を新規製品 (例: データベース、クラウドプロバイダー、ネットワークプラットフォーム) と統合する :ref:`一連の関連モジュールを記述 <developing_modules_in_groups>` したいです。

en: I want to refine my code:
ja: コードを改良したいです。

en: I want to :ref:`debug my module code <debugging_modules>`.
ja: :ref:`モジュールコードをデバッグ <debugging_modules>` したいです。

en: I want to :ref:`add tests <developing_testing>`.
ja: :ref:`テストを追加 <developing_testing>` したいです。

en: I want to :ref:`document my module <module_documenting>`.
ja: :ref:`モジュールをドキュメント化 <module_documenting>` したいです。

en: I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
ja: :ref:`ネットワークプラットフォームのモジュールセットを文書化 <documenting_modules_network>` したいです。

en: I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
ja: :ref:`クリーンで使いやすいモジュールコードのための規則とヒント <developing_modules_best_practices>` を適用したいです。

en: I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.
ja: :ref:`作成したコードが Python 2 および Python 3 で実行する <developing_python_3>` ようにしたいです。

en: I want to work on other development projects:
ja: 他の開発プロジェクトで作業したいです。

en: I want to :ref:`write a plugin <developing_plugins>`.
ja: :ref:`プラグインを記述 <developing_plugins>` したいです。

en: I want to :ref:`connect Ansible to a new source of inventory <developing_inventory>`.
ja: :ref:`Ansible を新しいインベントリーソースに接続 <developing_inventory>` したいです。

en: I want to :ref:`deprecate an outdated module <deprecating_modules>`.
ja: :ref:`古いモジュールを非推奨 <deprecating_modules>` にしたいです。

en: I want to contribute back to the Ansible project:
ja: Ansible プロジェクトに貢献したいです。

en: I want to :ref:`understand how to contribute to Ansible <ansible_community_guide>`.
ja: :ref:`Ansible への貢献方法を理解 <ansible_community_guide>` したいです。

en: I want to :ref:`contribute my module or plugin <developing_modules_checklist>`.
ja: :ref:`モジュールまたはプラグインに貢献 <developing_modules_checklist>` したいです。

en: I want to :ref:`understand the license agreement <contributor_license_agreement>` for contributions to Ansible.
ja: Ansible に参加するための :ref:`使用許諾契約を理解 <contributor_license_agreement>` したいです。

en: If you prefer to read the entire guide, here's a list of the pages in order.
ja: 本ガイドをすべて読む場合は、以下に示す順番でページを表示してください。

en: Migrating Roles to Roles in Collections on Galaxy
ja: ロールの、Galaxy のコレクション内のロールへの移行

en: You can migrate any existing standalone role into a collection and host the collection on Galaxy. With Ansible collections, you can distribute many roles in a single cohesive unit of re-usable automation. Inside a collection, you can share custom plugins across all roles in the collection instead of duplicating them in each role's :file:`library/`` directory.
ja: 既存のスタンドアロンロールをコレクションに移行し、コレクションを Galaxy 上でホストすることができます。Ansible コレクションを使用すると、再利用可能な自動化の 1 つのまとまったユニットで多くのロールを配布できます。コレクションの中では、カスタムプラグインを各ロールの :file:`library/`` ディレクトリーに複製するのではなく、コレクション内のすべてのロールで共有することができます。

en: You must migrate roles to collections if you want to distribute them as certified Ansible content.
ja: ロールを認定済みの Ansible コンテンツとして配布する場合は、ロールをコレクションに移行する必要があります。

en: If you want to import your collection to Galaxy, you need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_.
ja: コレクションを Galaxy にインポートする場合は、`Galaxy 名前空間 <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_ が必要です。

en: See :ref:`developing_collections` for details on collections.
ja: コレクションの詳細は、「:ref:`developing_collections`」を参照してください。

en: Comparing standalone roles to collection roles
ja: スタンドアロンロールとコレクションロールの比較

en: :ref:`Standalone roles <playbooks_reuse_roles>` have the following directory structure:
ja: :ref:`Standalone roles <playbooks_reuse_roles>` に、以下のディレクトリー構造があります。

en: The highlighted directories above will change when you migrate to a collection-based role. The collection directory structure includes a :file:`roles/` directory:
ja: 上記の強調表示されたディレクトリーは、コレクションベースのロールへの移行時に変化します。コレクションディレクトリー構造には、:file:`roles/` ディレクトリーが含まれます。

en: You will need to use the Fully Qualified Collection Name (FQCN) to use the roles and plugins when you migrate your role into a collection. The FQCN is the combination of the collection ``namespace``, collection ``name``, and the content item you are referring to.
ja: ロールをコレクションに移行するときにロールおよびプラグインを使用するために、完全修飾コレクション名 (FQCN) を使用する必要があります。FQCN は、コレクション ``namespace``、コレクション ``name``、および参照するコンテンツアイテムの組み合わせになります。

en: So for example, in the above collection, the FQCN to access  ``role1`` would be:
ja: たとえば、上記のコレクションでは、``role1`` にアクセスする FQCN は以下のようになります。

en: A collection can contain one or more roles in the :file:`roles/` directory and these are almost identical to standalone roles, except you need to move plugins out of the individual roles, and use the :abbr:`FQCN (Fully Qualified Collection Name)` in some places, as detailed in the next section.
ja: コレクションには、:file:`roles/` ディレクトリーに 1 つまたは複数のロールを含めることができ、これらのロールはスタンドアロンロールとほぼ同じです。ただし、個別のロールからプラグインを外に移動し、一部では :abbr:`FQCN (Fully Qualified Collection Name)` を使用します。これは、次のセクションで詳細に説明します。

en: In standalone roles, some of the plugin directories referenced their plugin types in the plural sense; this is not the case in collections.
ja: スタンドアロンロールでは、プラグインディレクトリーの一部が複数の意味でプラグインタイプを参照していました。コレクションではこのようになりません。

en: Migrating a role to a collection
ja: ロールのコレクションへの移行

en: To migrate from a standalone role that contains no plugins to a collection role:
ja: プラグインが含まれないスタンドアロンロールからコレクションロールに移行するには、以下を行います。

en: Create a local :file:`ansible_collections` directory and ``cd`` to this new directory.
ja: ローカルの :file:`ansible_collections` ディレクトリーを作成し、この新しいディレクトリーに ``cd`` を作成します。

en: Create a collection. If you want to import this collection to Ansible Galaxy, you need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_.
ja: コレクションを作成します。このコレクションを Ansible Galaxy にインポートする場合は、`Galaxy 名前空間 <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_ が必要です。

en: This creates the collection directory structure.
ja: これにより、コレクションディレクトリー構造が作成されます。

en: Copy the standalone role directory into the :file:`roles/` subdirectory of the collection. Roles in collections cannot have hyphens in the role name. Rename any such roles to use underscores instead.
ja: スタンドアロンのロールディレクトリーをコレクションの :file:`roles/` サブディレクトリーにコピーします。コレクション内のロールにはロール名にハイフンを設定できません。このようなロールは名前を変更し、代わりにアンダースコアを使用するようにします。

en: Update ``galaxy.yml`` to include any role dependencies.
ja: ``galaxy.yml`` を更新して、ロールの依存関係を追加します。

en: Update the collection README.md file to add links to any role README.md files.
ja: コレクション README.md ファイルを更新して、ロールの README.md ファイルへのリンクを追加します。

en: Migrating a role that contains plugins to a collection
ja: プラグインが含まれるロールからコレクションへの移行

en: To migrate from a standalone role that has plugins to a collection role:
ja: プラグインが含まれないスタンドアロンロールからコレクションロールに移行するには、以下を行います。

en: Create a local :file:`ansible_collections directory` and ``cd`` to this new directory.
ja: ローカルの :file:`ansible_collections directory` および ``cd`` をこの新しいディレクトリーに作成します。

en: Move any modules to the :file:`plugins/modules/` directory.
ja: モジュールを :file:`plugins/modules/` ディレクトリーに移動します。

en: Move any other plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory.  See :ref:`migrating_plugins_collection` for additional steps that may be required.
ja: その他のプラグインを適切な :file:`plugins/PLUGINTYPE/` ディレクトリーに移動します。必要となる可能性のある追加手順については、「:ref:`migrating_plugins_collection`」を参照してください。

en: Change any references to the role to use the :abbr:`FQCN (Fully Qualified Collection Name)`.
ja: :abbr:`FQCN (Fully Qualified Collection Name)` を使用するように、ロールへの参照を変更します。

en: You can alternately use the ``collections`` keyword to simplify this:
ja: 別の方法では、``collections`` キーワードを使用してこれを単純化することもできます。

en: Migrating other role plugins to a collection
ja: 他のロールプラグインからコレクションへの移行

en: To migrate other role plugins to a collection:
ja: その他のロールプラグインをコレクションに移行するには、以下を実行します。

en: Move each nonmodule plugins to the appropriate :file:`plugins/PLUGINTYPE/` directory. The :file:`mynamespace/mycollection/plugins/README.md` file explains the types of plugins that the collection can contain within optionally created subdirectories.
ja: モジュール以外の各プラグインを適切な :file:`plugins/PLUGINTYPE/` ディレクトリーに移動します。:file:`mynamespace/mycollection/plugins/README.md` ファイルは、任意で作成されたサブディレクトリー内にコレクションが含めることができるプラグインのタイプを説明します。

en: Update documentation to use the FQCN. Plugins that use ``doc_fragments`` need to use FQCN (for example, ``mydocfrag`` becomes ``mynamespace.mycollection.mydocfrag``).
ja: FQCN を使用するようにドキュメントを更新します。``doc_fragments`` を使用するプラグインは、FQCN を使用する必要があります (たとえば、``mydocfrag`` は ``mynamespace.mycollection.mydocfrag`` になります)。

en: Update relative imports work in collections to start with a period.  For example, :file:`./filename` and :file:`../asdfu/filestuff` works but :file:`filename` in same directory must be updated to :file:`./filename`.
ja: コレクション内の相対インポート作業を更新し、ピリオドで開始します。たとえば、:file:`./filename` および :file:`../asdfu/filestuff` は有効ですが、同じディレクトリー内の :file:`filename` を :file:`./filename` に更新する必要があります。

en: If you have a custom ``module_utils`` or import from ``__init__.py``, you must also:
ja: カスタムの ``module_utils`` がある、または ``__init__.py`` からインポートする場合は、以下も必要になります。

en: Change the Python namespace for custom ``module_utils`` to use the :abbr:`FQCN (Fully Qualified Collection Name)` along with the ``ansible_collections`` convention. See :ref:`update_module_utils_role`.
ja: カスタム ``module_utils`` の Python 名前空間が、``ansible_collections`` 規則と共に :abbr:`FQCN (Fully Qualified Collection Name)` を使用するように変更します。:ref:`update_module_utils_role` を参照してください。

en: Change how you import from ``__init__.py``. See :ref:`update_init_role`.
ja: ``__init__.py`` からインポートする方法を変更します。「:ref:`update_init_role`」を参照してください。

en: Updating ``module_utils``
ja: ``module_utils`` の更新

en: If any of your custom modules use a custom module utility, once you migrate to a collection you cannot address the module utility in the top level ``ansible.module_utils`` Python namespace. Ansible does not merge content from collections into the Ansible internal Python namespace. Update any Python import statements that refer to custom module utilities when you migrate your custom content to collections. See :ref:`module_utils in collections <collection_module_utils>` for more details.
ja: カスタムモジュールのいずれかがカスタムモジュールユーティリティーを使用している場合は、コレクションに移行すると、上位レベルの ``ansible.module_utils`` Python 名前空間でモジュールユーティリティーを扱うことができません。Ansible は、コレクションのコンテンツを Ansible 内部の Python 名前空間にマージしません。カスタムコンテンツをコレクションに移行する際は、カスタムモジュールユーティリティーを参照している Python の import 文を更新してください。詳細は、「:ref:`コレクションの module_utils <collection_module_utils>`」を参照してください。

en: When coding with ``module_utils`` in a collection, the Python import statement needs to take into account the :abbr:`FQCN (Fully Qualified Collection Name)` along with the ``ansible_collections`` convention. The resulting Python import looks similar to the following example:
ja: コレクションで ``module_utils`` を使用してコーディングする場合、Python の import ステートメントは ``ansible_collections`` 規則とともに :abbr:`FQCN (Fully Qualified Collection Name)` を考慮する必要があります。作成される Python インポートは以下のようになります。

en: You need to follow the same rules in changing paths and using namespaced names for subclassed plugins.
ja: パスの変更と同じルールに従い、サブクラスのプラグインに名前空間を使用した名前を使用する必要があります。

en: The following example code snippets show a Python and a PowerShell module using both default Ansible ``module_utils`` and those provided by a collection. In this example the namespace is ``ansible_example`` and the collection is ``community``.
ja: 以下のスニペットの例は、デフォルトの Ansible ``module_utils`` と、コレクションの両方を使用する Python および PowerShell モジュールを示しています。この例では、名前空間は ``ansible_example`` で、コレクションは ``community`` です。

en: In the Python example the ``module_utils`` is ``helper`` and the :abbr:`FQCN (Fully Qualified Collection Name)` is ``ansible_example.community.plugins.module_utils.helper``:
ja: Python の例では、``module_utils`` が ``helper`` で、:abbr:`FQCN (Fully Qualified Collection Name)` は ``ansible_example.community.plugins.module_utils.helper`` です。

en: In the PowerShell example the ``module_utils`` is ``hyperv`` and the :abbr:`FQCN (Fully Qualified Collection Name)` is ``ansible_example.community.plugins.module_utils.hyperv``:
ja: PowerShell の例では、``module_utils`` が ``hyperv`` で、:abbr:`FQCN (Fully Qualified Collection Name)` は ``ansible_example.community.plugins.module_utils.hyperv`` です。

en: Importing from __init__.py
ja: __init__.py からのインポート

en: Because of the way that the CPython interpreter does imports, combined with the way the Ansible plugin loader works, if your custom embedded module or plugin requires importing something from an :file:`__init__.py` file, that also becomes part of your collection. You can either originate the content inside a standalone role or use the file name in the Python import statement. The following example is an :file:`__init__.py` file that is part of a callback plugin found inside a collection named ``ansible_example.community``.
ja: CPython インタープリターがインポートを行う方法と、Ansible プラグインローダーが動作する方法を組み合わせることで、カスタムの組み込みモジュールやプラグインが :file:`__init__.py` ファイルから何かをインポートする必要がある場合は、それもコレクションの一部になります。コンテンツをスタンドアロンのロールの内部で生成するか、Python の import 文でファイル名を使用することができます。次の例は、``ansible_example.community`` という名前のコレクションの中にある callback プラグインの一部である :file:`__init__.py` ファイルです。

en: Example: Migrating a standalone role with plugins to a collection
ja: 例: プラグインを持つスタンドアロンロールをコレクションに移行

en: In this example we have a standalone role called ``my-standalone-role.webapp`` to emulate a standalone role that contains dashes in the name (which is not valid in collections). This standalone role contains a custom module in the ``library/`` directory called ``manage_webserver``.
ja: この例では、``my-standalone-role.webapp`` という名前のスタンドアロンのロールがあり、名前にダッシュが含まれるスタンドアロンのロールをエミュレートします (コレクションで有効なものではありません)。このスタンドアロンロールには、``manage_webserver`` と呼ばれる ``library/`` ディレクトリーのカスタムモジュールが含まれます。

en: Create a new collection, for example, ``acme.webserver``:
ja: 新規コレクションを作成します (``acme.webserver`` など)。

en: Create the ``webapp`` role inside the collection and copy all contents from the standalone role:
ja: コレクション内に ``webapp`` ロールを作成し、standalone ロールからすべてのコンテンツをコピーします。

en: Move the ``manage_webserver`` module to its new home in ``acme/webserver/plugins/modules/``:
ja: ``manage_webserver`` モジュールを ``acme/webserver/plugins/modules/`` 内の新しいホームに移動します。

en: This example changed the original source file ``manage_webserver.py`` to the destination file ``manage.py``. This is optional but the :abbr:`FQCN (Fully Qualified Collection Name)` provides the ``webserver`` context as ``acme.webserver.manage``.
ja: この例では、元のソースファイル ``manage_webserver.py`` を宛先ファイル ``manage.py`` に変更しました。これは任意ですが、:abbr:`FQCN (Fully Qualified Collection Name)` は、``acme.webserver.manage`` として ``webserver`` のコンテキストを提供します。

en: Change ``manage_webserver`` to ``acme.webserver.manage`` in :file:`tasks/` files in the role ( for example, ``my-standalone-role.webapp/tasks/main.yml``) and any use of the original module name.
ja: ロール内の :file:`tasks/` ファイルで ``manage_webserver`` を ``acme.webserver.manage`` に変更 (``my-standalone-role.webapp/tasks/main.yml`` など) し、元のモジュール名を使用します。

en: This name change is only required if you changed the original module name, but illustrates content referenced by :abbr:`FQCN (Fully Qualified Collection Name)` can offer context and in turn can make module and plugin names shorter. If you anticipate using these modules independent of the role, keep the original naming conventions. Users can add the  :ref:`collections keyword <collections_using_playbook>` in their playbooks. Typically roles are an abstraction layer and users won't use components of the role independently.
ja: この名前の変更は、元のモジュール名を変更した場合にのみ必要ですが、:abbr:`FQCN (Fully Qualified Collection Name)` で参照されるコンテンツを例示することで、コンテキストを提供し、ひいてはモジュールやプラグインの名前を短くすることができます。これらのモジュールをロールとは関係なく使用することを想定している場合は、元の命名規則を維持してください。ユーザーは、Playbook に :ref:`コレクションのキーワード <collections_using_playbook>` を追加することができます。通常、ロールは抽象レイヤーであり、ユーザーはロールのコンポーネントを個別に使用することはありません。

en: Example: Supporting standalone roles and migrated collection roles in a downstream RPM
ja: 例: ダウンストリーム RPM でのスタンドアロンロールと移行されたコレクションロールのサポート

en: A standalone role can co-exist with its collection role counterpart (for example, as part of a support lifecycle of a product). This should only be done for a transition period, but these two can exist in downstream in packages such as RPMs. For example, the RHEL system roles could coexist with an `example of a RHEL system roles collection <https://github.com/maxamillion/collection-rhel-system-roles>`_ and provide existing backwards compatibility with the downstream RPM.
ja: スタンドアロンのロールは、対応するコレクションロールと共存することができます (例: 製品のサポートライフサイクルの一部として)。これは移行期間のみ行うべきですが、これら 2 つは RPM などのパッケージでダウンストリームに存在することができます。たとえば、RHEL のシステムロールは `example of a RHEL system roles collection <https://github.com/maxamillion/collection-rhel-system-roles>`_ と共存し、ダウンストリーム RPM との既存の後方互換性を提供することができます。

en: This section walks through an example creating this coexistence in a downstream RPM and requires Ansible 2.9.0 or later.
ja: 本セクションでは、ダウンストリーム RPM でこの共存を作成し、Ansible 2.9.0 以降が必要になります。

en: To deliver a role as both a standalone role and a collection role:
ja: スタンドアロンロールとコレクションロールの両方としてロールを提供するには、以下を実行します。

en: Place the collection in  :file:`/usr/local/share/py38-ansible/collections/ansible_collections/`.
ja: コレクションを :file:`/usr/local/share/py38-ansible/collections/ansible_collections/` に置きます。

en: Copy the contents of the role inside the collection into a directory named after the standalone role and place the standalone role in  :file:`/usr/local/share/py38-ansible/roles/`.
ja: コレクション内のロールの内容をスタンドアロンロールにちなんで名付けられたディレクトリーにコピーし、スタンドアロンロールを :file:`/usr/local/share/py38-ansible/roles/` に置きます。

en: All previously bundled modules and plugins used in the standalone role are now referenced by :abbr:`FQCN (Fully Qualified Collection Name)` so even though they are no longer embedded, they can be found from the collection contents.This is an example of how the content inside the collection is a unique entity and does not have to be bound to a role or otherwise. You could alternately create two separate collections: one for the modules and plugins and another for the standalone role to migrate to. The role must use the modules and plugins as :abbr:`FQCN (Fully Qualified Collection Name)`.
ja: スタンドアロンロールで使用されていた、以前にバンドルされていたモジュールやプラグインは、すべて :abbr:`FQCN (Fully Qualified Collection Name)` で参照されるようになりました。そのため、それらはもはや埋め込まれていないにもかかわらず、コレクションのコンテンツから見つけることができます。これは、コレクション内のコンテンツが固有のエンティティーであり、ロールなどに縛られる必要がないことを示す例です。別の方法として、2 つの独立したコレクションを作成することもできます。1 つはモジュールとプラグイン用、もう 1 つは移行先のスタンドアロンロール用です。ロールは、モジュールとプラグインを :abbr:`FQCN (Fully Qualified Collection Name)` として使用する必要があります。

en: The following is an example RPM spec file that accomplishes this using this example content:
ja: 以下は、このサンプルの内容を使用してこれを実現する RPM 仕様ファイルの例です。

en: Using ``ansible.legacy`` to access local custom modules from collections-based roles
ja: ``ansible.legacy`` を使用したコレクションベースのロールからローカルのカスタムモジュールへのアクセス

en: Some roles use :ref:`local custom modules <developing_locally>` that are not part of the role itself. When you move these roles into collections, they can no longer find those custom plugins. You can add the synthetic collection ``ansible.legacy`` to enable legacy behavior and find those custom plugins. Adding ``ansible.legacy`` configures your role to search the pre-collections default paths for modules and plugins.
ja: 一部のロールは、ロール自体の一部ではない :ref:`local custom modules <developing_locally>` を使用します。これらのロールをコレクションに移動すると、それらのカスタムプラグインを見つけることができなくなります。統合的なコレクション ``ansible.legacy`` を追加して、レガシー動作を有効にし、これらのカスタムプラグインを見つけることができます。``ansible.legacy`` を追加することで、ロールを設定し、モジュールおよびプラグインのプレコレクションのデフォルトパスを検索します。

en: To enable a role hosted in a collection to find legacy custom modules and other plugins hosted locally:
ja: コレクションにホストされているロールが、ローカルでホストされている従来のカスタムモジュールやその他のプラグインを検索できるようにするには、以下を行います。

en: Edit the role's ``meta/main.yml`` and add the ``ansible.legacy`` collection to your collection-hosted role to enable the use of legacy custom modules and plugins for all tasks:
ja: ロールの ``meta/main.yml`` を編集し、``ansible.legacy`` コレクションをコレクションホストのロールに追加し、すべてのタスクにレガシーのカスタムモジュールおよびプラグインを使用できるようにします。

en: Alternatively, you can update the tasks directly by changing ``local_module_name`` to ``ansible.legacy.local_module_name``.
ja: または、``local_module_name`` を ``ansible.legacy.local_module_name`` に変更するとタスクを直接更新できます。

en: The lifecycle of an Ansible module or plugin
ja: Ansible モジュールまたはプラグインのライフサイクル

en: Modules and plugins in the main Ansible repository have a defined life cycle, from the first introduction to final removal. The module and plugin lifecycle is tied to the `Ansible release cycle <release_cycle>`. A module or plugin may move through these four stages:
ja: メインの Ansible リポジトリーのモジュールおよびプラグインには、最初の導入から最後の削除までライフサイクルが定義されます。モジュールおよびプラグインのライフサイクルは、`Ansible release cycle <release_cycle>` に紐づけられ、モジュールまたはプラグインは、次の 4 つの段階を通過する可能性があります。

en: When a module or plugin is first accepted into Ansible, we consider it in tech preview and will mark it as such in the documentation.
ja: モジュールまたはプラグインが最初に Ansible に受け入れられると、テクノロジープレビューでそれが考慮され、そのようにマークされます。

en: If a module or plugin matures, the 'preview' mark in the documentation is removed. Backward compatibility for these modules and plugins is maintained but not guaranteed, which means their parameters should be maintained with stable meanings.
ja: モジュールまたはプラグインが成熟すると、ドキュメントの「preview」マークが削除されます。これらのモジュールおよびプラグインの後方互換性は維持されますが保証されません。これは、これらのパラメーターが安定した意味で維持されるべきことを意味します。

en: If a module's or plugin's target API changes radically, or if someone creates a better implementation of its functionality, we may mark it deprecated. Modules and plugins that are deprecated are still available but they are reaching the end of their life cycle. We retain deprecated modules and plugins for 4 release cycles with deprecation warnings to help users update playbooks and roles that use them.
ja: モジュールまたはプラグインのターゲット API が大幅に変更された場合、または誰かがその機能に対してより良い実装を作成した場合は、非推奨と表示することがあります。非推奨のモジュールまたはプラグインは引き続き利用できますが、ライフサイクルの終わりに近づいています。非推奨のモジュールまたはプラグインは 4 つのリリースサイクルの間保持され、ユーザーはそれを使用する Playbook とロールを更新できるように非推奨の警告が表示されます。

en: When a module or plugin has been deprecated for four release cycles, it is removed and replaced with a tombstone entry in the routing configuration. Modules and plugins that are removed are no longer shipped with Ansible. The tombstone entry helps users find alternative modules and plugins.
ja: 4 つのリリースサイクルでモジュールまたはプラグインは非推奨となり、ルーティング設定の tombstone エントリーに置き換えられます。削除されたモジュールおよびプラグインは Ansible に同梱されなくなります。tombstone エントリーは、別のモジュールおよびプラグインを見つけることができます。

en: For modules and plugins in collections, the lifecycle is similar. Since ansible-base 2.10, it is no longer possible to mark modules as 'preview' or 'stable'.
ja: コレクションにあるモジュールおよびプラグインでは、ライフサイクルが類似しています。ansible-base 2.10 では、モジュールを「preview」または「stable」のマークを付けることができなくなります。

en: Deprecating modules and plugins in the Ansible main repository
ja: Ansible メインリポジトリーでのモジュールおよびプラグインの非推奨化

en: To deprecate a module in ansible-core, you must:
ja: ansible-core でモジュールを非推奨にするには、以下を行う必要があります。

en: Rename the file so it starts with an ``_``, for example, rename ``old_cloud.py`` to ``_old_cloud.py``. This keeps the module available and marks it as deprecated on the module index pages.
ja: ファイルの名前を ``_`` で始まるように変更します。たとえば、``old_cloud.py`` の名前を ``_old_cloud.py`` に変更します。これにより、モジュールが利用可能のままとなり、モジュールインデックスページで非推奨としてマークされます。

en: Mention the deprecation in the relevant changelog (by creating a changelog fragment with a section ``deprecated_features``).
ja: (``deprecated_features`` セクションを使用して changelog フラグメントを作成することで) 関連する変更ログで非推奨となったことを説明します。

en: Reference the deprecation in the relevant ``porting_guide_core_x.y.rst``.
ja: 関連する ``porting_guide_core_x.y.rst`` で非推奨化を参照します。

en: Add ``deprecated:`` to the documentation with the following sub-values:
ja: 次のサブ値を使用して、``deprecated:`` をドキュメントに追加します。

en: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:.
ja: ``"2.10"`` などの ``string`` (モジュールがドキュメントのみのモジュールスタブに置き換えられる Ansible のバージョン)。通常、現在のリリース +4 になります。:removed_by_date: と相互に排他的です。

en: (Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
ja: (ansible-base 2.10 に追加されます)。モジュールの削除時に ISO 8601 形式の日付。通常は、モジュールが非推奨になってから 2 年間となります。このモジュールでは、:removed_in: と相互排他的になります。

en: why
ja: 理由

en: Optional string that used to detail why this has been removed.
ja: これが削除された理由の詳細に使用される任意の文字列です。

en: alternative
ja: 代替方法

en: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``.
ja: ユーザーが代わりにすべきことを通知します (例: ``Use M(whatmoduletouseinstead) instead.``)。

en: For an example of documenting deprecation, see this `PR that deprecates multiple modules <https://github.com/ansible/ansible/pull/43781/files>`_. Some of the elements in the PR might now be out of date.
ja: ドキュメントの非推奨の例は、「`複数のモジュールを非推奨にする PR <https://github.com/ansible/ansible/pull/43781/files>`_」を参照してください。PR の一部の要素が最新でない可能性があります。

en: Deprecating modules and plugins in a collection
ja: コレクションでのモジュールおよびプラグインの非推奨化

en: To deprecate a module in a collection, you must:
ja: コレクションでモジュールを非推奨にするには、以下を行う必要があります。

en: Add a ``deprecation`` entry to ``plugin_routing`` in ``meta/runtime.yml``. For example, to deprecate the module ``old_cloud``, add:
ja: ``meta/runtime.yml`` の ``plugin_routing`` に ``deprecation`` エントリーを追加します。たとえば、モジュール ``old_cloud`` を非推奨にするには、以下を追加します。

en: For other plugin types, you have to replace ``modules:`` with ``<plugin_type>:``, for example ``lookup:`` for lookup plugins.
ja: 他のプラグインタイプの場合、``modules:`` を ``<plugin_type>:`` に置き換える必要があります (検索プラグインの場合は ``lookup:`` など)。

en: Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted date after which the module will be removed in a new major version of the collection.
ja: ``removal_version`` の代わりに、コレクションの新しいメジャーバージョンでモジュールが削除されるまでの ISO 8601 形式の日付を入れた ``removal_date`` を使用することもできます。

en: Mention the deprecation in the relevant changelog. If the collection uses ``antsibull-changelog``, create a changelog fragment with a section ``deprecated_features``.
ja: 関連する変更ログで非推奨になったことを説明します (コレクションが ``antsibull-changelog`` を使用する場合は、セクション ``deprecated_features`` を指定して changelog フラグメントを作成します)。

en: Add ``deprecated:`` to the documentation of the module or plugin with the following sub-values:
ja: 以下のサブ値を含むモジュールまたはプラグインのドキュメントに ``deprecated:`` を追加します。

en: Changing a module or plugin name in the Ansible main repository
ja: Ansible メインリポジトリーのモジュールまたはプラグイン名の変更

en: You can also rename a module and keep a deprecated alias to the old name by using a symlink that starts with _. This example allows the ``stat`` module to be called with ``fileinfo``, making the following examples equivalent::
ja: _ で始まるシンボリックリンクを使用して、モジュールの名前を変更し、非推奨のエイリアスを古い名前に保つこともできます。この例では、``stat`` モジュールを ``fileinfo`` で呼び出すことができるため、次の例は同等になります。

en: Renaming a module or plugin in a collection, or redirecting a module or plugin to another collection
ja: コレクションでのモジュールまたはプラグインの名前変更、またはモジュールまたはプラグインを別のコレクションにリダイレクト

en: To rename a module or plugin in a collection, or to redirect a module or plugin to another collection, you need to add a ``redirect`` entry to ``plugin_routing`` in ``meta/runtime.yml``. For example, to redirect the module ``old_cloud`` to ``foo.bar.new_cloud``, add:
ja: コレクションでモジュールまたはプラグインの名前を変更するか、モジュールまたはプラグインを別のコレクションにリダイレクトするには、``redirect`` エントリーを、``meta/runtime.yml`` の ``plugin_routing``に追加する必要があります。たとえば、モジュール ``old_cloud`` を ``foo.bar.new_cloud`` にリダイレクトする場合は、以下を追加します。

en: If you want to deprecate the old name, add a ``deprecation:`` entry (see above):
ja: 古い名前を非推奨にするには、``deprecation:`` エントリーを追加します (上記を参照)。

en: You need to use the Fully Qualified Collection Name (FQCN) of the new module/plugin name, even if it is located in the same collection as the redirect. By using a FQCN from another collection, you redirect the module/plugin to that collection.
ja: 新規モジュール/プラグイン名の完全修飾コレクション名 (FQCN) を使用する必要があります。これは、リダイレクトと同じコレクションにある場合でも、別のコレクションから FQCN を使用し、モジュール/プラグインをそのコレクションにリダイレクトします。

en: If you need to support Ansible 2.9, please note that Ansible 2.9 does not know about ``meta/runtime.yml``. With Ansible 2.9 you can still rename plugins and modules inside one collection by using symbolic links. Note that ansible-base 2.10, ansible-core 2.11, and newer will prefer ``meta/runtime.yml`` entries over symbolic links.
ja: Ansible 2.9 をサポートする必要がある場合、Ansible 2.9 は ``meta/runtime.yml`` を認識しない点に注意してください。Ansible 2.9 では、シンボリックリンクを使用して、1 つのコレクション内のプラグインとモジュールの名前を変更できます。ansible-base 2.10、ansible-core 2.11 以降はシンボリックリンクよりも ``meta/runtime.yml`` エントリーを使用することが推奨されます。

en: Tombstoning a module or plugin in a collection
ja: コレクションでモジュールまたはプラグインを破棄

en: To remove a deprecated module or plugin from a collection, you need to tombstone it:
ja: コレクションから非推奨のモジュールまたはプラグインを削除するには、それを破棄する必要があります。

en: Remove the module or plugin file with related files like tests, documentation references, and documentation.
ja: テスト、ドキュメント参照、ドキュメントなど、関連ファイルでモジュールまたはプラグインファイルを削除します。

en: Add a tombstone entry in ``meta/runtime.yml``. For example, to tombstone the module ``old_cloud``, add:
ja: ``meta/runtime.yml`` に tombstone エントリーを追加します。たとえば、モジュール ``old_cloud`` を廃棄するには、以下を追加します。

en: Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted date. The date should be the date of the next major release.
ja: ``removal_version`` の代わりに、ISO 8601 形式の日付を入れた ``removal_date`` を使用することもできます。この日付は、次のメジャーリリースの日付である必要があります。

en: Ansible architecture
ja: Ansible アーキテクチャー

en: Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs.
ja: Ansible は、クラウドプロビジョニング、設定管理、アプリケーションのデプロイメント、サービス内オーケストレーション、およびその他の IT のニーズを自動化する非常にシンプルな IT 自動化エンジンです。

en: Being designed for multi-tier deployments since day one, Ansible models your IT infrastructure by describing how all of your systems inter-relate, rather than just managing one system at a time.
ja: Ansible は、リリースされたその日から多層デプロイメント用に設計されており、システムを 1 つずつ管理する代わりに、すべてのシステムがどのように相互に関連しているかを記述することで、IT インフラストラクチャーをモデル化します。

en: It uses no agents and no additional custom security infrastructure, so it's easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allow you to describe your automation jobs in a way that approaches plain English.
ja: エージェントを使用せず、カスタムセキュリティーインフラストラクチャーを追加しないため、簡単にデプロイメントできます。最も重要なことは、非常に単純な言語 (YAML を Ansible Playbook の形式で使用) を使用しているため、分かりやすい英語に近づける方法で自動化ジョブを記述できます。

en: In this section, we'll give you a really quick overview of how Ansible works so you can see how the pieces fit together.
ja: 本セクションでは、Ansible の動作の概要を簡単に説明します。これにより各ピースがどのように組み合わされているかを確認できます。

en: Modules
ja: モジュール

en: Ansible works by connecting to your nodes and pushing out scripts called "Ansible modules" to them. Most modules accept parameters that describe the desired state of the system. Ansible then executes these modules (over SSH by default), and removes them when finished. Your library of modules can reside on any machine, and there are no servers, daemons, or databases required.
ja: Ansible は、ノードに接続し、「Ansible モジュール」と呼ばれるスクリプトをノードにプッシュすることで機能します。ほとんどのモジュールは、システムの希望の状態を記述するパラメーターを受け入れます。その後、Ansible はこれらのモジュールを (デフォルトでは SSH 上で) 実行して、終了すると削除されます。モジュールのライブラリーはどのマシンにも配置でき、サーバー、デーモン、またはデータベースは必要ありません。

en: You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, and so on).
ja: :ref:`独自のモジュールを記述 <developing_modules_general>` ができますが、最初に :ref:`記述すべきかどうか <developing_modules>` を検討する必要があります。通常、任意のターミナルプログラム、テキストエディター、およびおそらくバージョン管理システムを使用して、コンテンツへの変更を追跡します。JSON を返すことができる任意の言語 (Ruby、Python、bash など) で特殊なモジュールを作成できます。

en: Module utilities
ja: モジュールユーティリティー

en: When multiple modules use the same code, Ansible stores those functions as module utilities to minimize duplication and maintenance. For example, the code that parses URLs is ``lib/ansible/module_utils/url.py``. You can :ref:`write your own module utilities <developing_module_utilities>` as well. Module utilities may only be written in Python or in PowerShell.
ja: 複数のモジュールが同じコードを使用する場合は、Ansible がこの機能をモジュールユーティリティーとして保存し、重複とメンテナンスを最小限に抑えます。たとえば、URL を解析するコードは ``lib/ansible/module_utils/url.py`` となります。:ref:`独自のモジュールユーティリティーを記述 <developing_module_utilities>` をすることもできます。モジュールユーティリティーは、Python または PowerShell でのみ記述できます。

en: Plugins
ja: プラグイン

en: :ref:`Plugins <plugins_lookup>` augment Ansible's core functionality. While modules execute on the target system in separate processes (usually that means on a remote system), plugins execute on the control node within the ``/usr/bin/ansible`` process. Plugins offer options and extensions for the core features of Ansible - transforming data, logging output, connecting to inventory, and more. Ansible ships with a number of handy plugins, and you can easily :ref:`write your own <developing_plugins>`. For example, you can write an :ref:`inventory plugin <developing_inventory>` to connect to any datasource that returns JSON. Plugins must be written in Python.
ja: :ref:`Plugins <plugins_lookup>` は、Ansible のコア機能を拡張するものです。モジュールがターゲットシステムの別のプロセス (通常はリモートシステム上) で実行されるのに対し、プラグインは、``/usr/bin/ansible`` プロセス内のコントロールノードで実行されます。プラグインは、データの変換、出力のロギング、インベントリーへの接続など、Ansible のコア機能のオプションや拡張機能を提供します。Ansible には便利なプラグインが多数同梱されており、簡単に :ref:`自作 <developing_plugins>` できます。たとえば、JSON を返すあらゆるデータソースに接続するための :ref:`inventory プラグイン <developing_inventory>` を記述することができます。プラグインは Python で記述されている必要があります。

en: Inventory
ja: インベントリー

en: By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) that puts all of your managed machines in groups of your own choosing.
ja: デフォルトでは、Ansible は、自身が選択したグループにすべての管理マシンを配置するファイル (INI、YAML など) で管理するマシンを表します。

en: To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn't get linked up due to obscure NTP or DNS issues.
ja: 新しいマシンを追加する場合、追加の SSL 署名サーバーはないため、不明瞭な NTP または DNS の問題が原因で特定のマシンがリンクされなかった理由を判断するのに苦労することはありません。

en: If there's another source of truth in your infrastructure, Ansible can also connect to that. Ansible can draw inventory, group, and variable information from sources like EC2, Rackspace, OpenStack, and more.
ja: インフラストラクチャーに信頼できる別のソースがある場合は、Ansible もこれに接続できます。Ansible は、EC2、Rackspace、OpenStack などのソースからインベントリー、グループ、および変数情報を取り出すことができます。

en: Here's what a plain text inventory file looks like::
ja: プレーンテキストのインベントリーファイルは次のようになります。

en: Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/' or directly in the inventory file.
ja: インベントリーホストの一覧が作成されると、単純なテキストファイル形式で (「group_vars/」または「host_vars/」という名前のサブディレクトリー内、またはインベントリーファイルに直接) 割り当てることができます。

en: Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources like EC2, Rackspace, or OpenStack.
ja: または、上述のように、動的インベントリーを使用して、EC2、Rackspace、OpenStack のようなデータソースからインベントリーをプルすることもできます。

en: Playbooks
ja: Playbook

en: Playbooks can finely orchestrate multiple slices of your infrastructure topology, with very detailed control over how many machines to tackle at a time.  This is where Ansible starts to get most interesting.
ja: Playbook は、インフラストラクチャートポロジーの複数のスライスを細かく調整 (オーケストレーション) することができ、同時に取り組むマシンの数を非常に細かく制御することができます。ここからが、Ansible で最も魅力的な点になります。

en: Ansible's approach to orchestration is one of finely-tuned simplicity, as we believe your automation code should make perfect sense to you years down the road and there should be very little to remember about special syntax or features.
ja: Ansible のオーケストレーションへのアプローチは、細かく調整された簡素化の 1 つです。通常、自動化コードは今後何年にも渡って完全に理解できるものであり、特別な構文や機能について覚えておくべきことはほとんどないためです。

en: Here's what a simple playbook looks like::
ja: 以下は単純な Playbook の例です。

en: The Ansible search path
ja: Ansible 検索パス

en: Modules, module utilities, plugins, playbooks, and roles can live in multiple locations. If you write your own code to extend Ansible's core features, you may have multiple files with similar or the same names in different locations on your Ansible control node. The search path determines which of these files Ansible will discover and use on any given playbook run.
ja: モジュール、モジュールユーティリティー、プラグイン、Playbook、およびロールは複数の場所に置くことができます。Ansible のコア機能を拡張するために独自のコードを作成する場合は、Ansible コントロールノードの異なる場所に同じ名前または類似する名前を持つファイルが複数存在する場合があります。検索パスにより、Ansible が特定の Playbook の実行で検出して使用するこれらのファイルが決まります。

en: Ansible's search path grows incrementally over a run. As Ansible finds each playbook and role included in a given run, it appends any directories related to that playbook or role to the search path. Those directories remain in scope for the duration of the run, even after the playbook or role has finished executing. Ansible loads modules, module utilities, and plugins in this order:
ja: Ansible の検索パスは、実行中に徐々に大きくなります。Ansible は、特定の実行に含まれる各 Playbook とロールを見つけると、その Playbook またはロールに関連するディレクトリーを検索パスに追加します。これらのディレクトリーは、Playbook またはロールの実行が終了した後でも、実行中はスコープ内に留まります。Ansible は、モジュール、モジュールユーティリティー、およびプラグインを次の順序で読み込みます。

en: Directories adjacent to a playbook specified on the command line. If you run Ansible with ``ansible-playbook /path/to/play.yml``, Ansible appends these directories if they exist:
ja: コマンドラインで指定した Playbook に隣接するディレクトリー。``ansible-playbook /path/to/play.yml`` で Ansible を実行し、そのディレクトリーが存在する場合は、Ansible がそのディレクトリーを追加します。

en: Directories adjacent to a playbook that is statically imported by a playbook specified on the command line. If ``play.yml`` includes ``- import_playbook: /path/to/subdir/play1.yml``, Ansible appends these directories if they exist:
ja: コマンドラインで指定された Playbook によって静的にインポートされる Playbook に隣接するディレクトリー。``play.yml`` に ``- import_playbook: /path/to/subdir/play1.yml`` が含まれていて、これらのディレクトリーが存在する場合は、Ansible がそのディレクトリーを追加します。

en: Subdirectories of a role directory referenced by a playbook. If ``play.yml`` runs ``myrole``, Ansible appends these directories if they exist:
ja: Playbook によって参照されるロールディレクトリーのサブディレクトリー。``play.yml`` が ``myrole`` を実行し、次のディレクトリーが存在する場合は、Ansible がそのディレクトリーを追加します。

en: Directories specified as default paths in ``ansible.cfg`` or by the related environment variables, including the paths for the various plugin types. See :ref:`ansible_configuration_settings` for more information. Sample ``ansible.cfg`` fields:
ja: ``ansible.cfg`` のデフォルトパスとして、またはさまざまなプラグインタイプのパスなど、関連する環境変数により指定されたディレクトリーて。詳細は、「:ref:`ansible_configuration_settings`」を参照してください。サンプルの ``ansible.cfg`` フィールドは以下のようになります。

en: Sample environment variables:
ja: 以下は、環境変数の例となります。

en: The standard directories that ship as part of the Ansible distribution.
ja: Ansible ディストリビューションに同梱される標準ディレクトリー。

en: Modules, module utilities, and plugins in user-specified directories will override the standard versions. This includes some files with generic names. For example, if you have a file named ``basic.py`` in a user-specified directory, it will override the standard ``ansible.module_utils.basic``.
ja: ユーザーが指定したディレクトリーにあるモジュール、モジュールユーティリティー、およびプラグインは標準バージョンを上書きします。これには、一般的な名前のファイルも含まれます。たとえば、ユーザー指定のディレクトリーに ``basic.py`` という名前のファイルがある場合は、標準の ``ansible.module_utils.basic`` を上書きします。

en: If you have more than one module, module utility, or plugin with the same name in different user-specified directories, the order of commands at the command line and the order of includes and roles in each play will affect which one is found and used on that particular play.
ja: 同じ名前のモジュール、モジュールユーティリティー、またはプラグインが複数のユーザー指定ディレクトリーにある場合、コマンドラインでのコマンドの順序や、各プレイでのインクルードとロールの順序は、その特定のプレイでどのモジュールが見つかり、使用されるかによって異なります。

en: Guidelines for Ansible Amazon AWS module development
ja: Ansible Amazon AWS モジュール開発のガイドライン

en: The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws>`_, source code `repository <https://github.com/ansible-collections/community.aws>`_) is maintained by the Ansible AWS Working Group.  For further information see the `AWS working group community page <https://github.com/ansible/community/wiki/aws>`_. If you are planning to contribute AWS modules to Ansible then getting in touch with the working group is a good way to start, especially because a similar module may already be under development.
ja: Ansible AWS コレクション (`Galaxy <https://galaxy.ansible.com/community/aws>`_ では、ソースコード `レポジトリー <https://github.com/ansible-collections/community.aws>`_) は、Ansible AWS のワーキンググループ維持されます。詳細は `AWS ワーキンググループのコミュニティーページ <https://github.com/ansible/community/wiki/aws>`_ を参照してください。AWS モジュールを Ansible に提供することを計画している場合は、特に同様のモジュールがすでに開発中である可能性があるため、ワーキンググループに連絡することから始めることが推奨されます。

en: Requirements
ja: 要件

en: Python Compatibility
ja: Python の互換性

en: AWS content in Ansible 2.9 and 1.x collection releases supported Python 2.7 and newer.
ja: Ansible 2.9 および 1.x コレクションリリースの AWS コンテンツは、Python 2.7 以降でサポートされます。

en: Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_.  Contributions to both collections that target the 2.0 or later collection releases can be written to support Python 3.6+ syntax.
ja: 両方のコレクションで 2.0 リリース以降、Python 2.7 サポートは AWS の `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_ に従って終了します。2.0 以降のコレクションリリースをターゲットとするコレクションの両方への貢献に、Python 3.6 以降の構文を記載することができます。

en: SDK Version Support
ja: SDK バージョンのサポート

en: Starting with the 2.0 releases of both collections, it is generally the policy to support the versions of botocore and boto3 that were released 12 months prior to the most recent major collection release, following semantic versioning (for example, 2.0.0, 3.0.0).
ja: 両方のコレクションの 2.0 リリース以降は、通常、最新のメジャーコレクションリリースの 12 か月前にリリースされた botocore と boto3 のバージョンをサポートするポリシーとなり、セマンティックバージョニング (たとえば、2.0.0、3.0.0 ) に従います。

en: Features and functionality that require newer versions of the SDK can be contributed provided they are noted in the module documentation:
ja: SDK の新しいバージョンを必要とする機能は、モジュールのドキュメントに記載されている場合に提供できます。

en: And handled using the ``botocore_at_least`` helper method:
ja: また、``botocore_at_least`` ヘルパーメソッドを使用して処理されます。

en: Maintaining existing modules
ja: 既存のモジュールのメンテナンス

en: Fixing bugs
ja: バグの修正

en: Bug fixes to code that relies on boto will still be accepted. When possible, the code should be ported to use boto3.
ja: boto に依存するコードに対するバグ修正は引き続き承認されます。可能であれば、このコードは、boto3 を使用するように移植する必要があります。

en: Adding new features
ja: 新しい機能の追加

en: Try to keep backward compatibility with relatively recent versions of boto3. That means that if you want to implement some functionality that uses a new feature of boto3, it should only fail if that feature actually needs to be run, with a message stating the missing feature and minimum required version of boto3.
ja: 比較的最近のバージョンの boto3 との下位互換性を保つようにしてください。つまり、boto3 の新機能を使用する一部の機能を実装する場合は、その機能を実際に実行する必要がある場合にのみ失敗し、欠落している機能と最低限必要な boto3 のバージョンを示すメッセージが表示されます。

en: Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3 supports a feature rather than version checking. For example, from the ``ec2`` module:
ja: 機能テスト (例: ``hasattr('boto3.module', 'shiny_new_method')``) を使用して、boto3 がバージョンチェックではなく機能をサポートしているかどうかを確認します。たとえば、``ec2`` モジュールからです。

en: Migrating to boto3
ja: boto3 への移行

en: Prior to Ansible 2.0, modules were written in either boto3 or boto. We are still porting some modules to boto3. Modules that still require boto should be ported to use boto3 rather than using both libraries (boto and boto3). We would like to remove the boto dependency from all modules.
ja: Ansible 2.0 より前、モジュールは boto3 または boto のいずれかで記述されていました。まだ、いくつかのモジュールを boto3 に移植しています。それでも boto が必要なモジュールは、両方のライブラリー (boto と boto3) を使用するのではなく、boto3 を使用するように移植する必要があります。すべてのモジュールから boto 依存関係を削除したいと考えています。

en: Porting code to AnsibleAWSModule
ja: AnsibleAWSModule へのコードの移植

en: Some old AWS modules use the generic ``AnsibleModule`` as a base rather than the more efficient ``AnsibleAWSModule``. To port an old module to ``AnsibleAWSModule``, change:
ja: 一部の古い AWS モジュールは、より効率的な ``AnsibleAWSModule`` ではなく、汎用の ``AnsibleModule`` をベースとして使用します。古いモジュールを ``AnsibleAWSModule`` に移植するには、以下を変更します。

en: to:
ja: 以下のように変更します。

en: Few other changes are required. AnsibleAWSModule does not inherit methods from AnsibleModule by default, but most useful methods are included. If you do find an issue, please raise a bug report.
ja: その他の変更が必要になります。AnsibleAWSModule はデフォルトで AnsibleModule のメソッドを継承しませんが、最も便利なメソッドが含まれています。問題を見つけた場合は、バグレポートを提出してください。

en: When porting, keep in mind that AnsibleAWSModule also will add the default ec2 argument spec by default. In pre-port modules, you should see common arguments specified with:
ja: ポート時には、AnsibleAWSModule はデフォルトでデフォルトの ec2 引数仕様も追加します。移植前モジュールでは、以下で指定された一般的な引数が表示されるはずです。

en: These can be replaced with:
ja: これは、次のものと置き換えることができます。

en: Creating new AWS modules
ja: 新規 AWS モジュールの作成

en: Use boto3 and AnsibleAWSModule
ja: boto3 および AnsibleAWSModule の使用

en: All new AWS modules must use boto3 and ``AnsibleAWSModule``.
ja: すべての新規 AWS モジュールは boto3 および ``AnsibleAWSModule`` を使用する必要があります。

en: ``AnsibleAWSModule`` greatly simplifies exception handling and library management, reducing the amount of boilerplate code. If you cannot use ``AnsibleAWSModule`` as a base, you must document the reason and request an exception to this rule.
ja: ``AnsibleAWSModule`` は、例外処理とライブラリー管理を大幅に簡素化し、boilerplate コードの量を削減します。``AnsibleAWSModule`` をベースとして使えない場合は、理由を文書化し、このルールの例外を要求する必要があります。

en: Naming your module
ja: モジュールの名前付け

en: Base the name of the module on the part of AWS that you actually use. (A good rule of thumb is to take whatever module you use with boto as a starting point).  Don't further abbreviate names - if something is a well known abbreviation of a major component of AWS (for example, VPC or ELB), that's fine, but don't create new ones independently.
ja: 実際に使用する AWS の一部であるモジュール名をベースにします (経験則として、boto で使用するモジュールを開始点として使用することが推奨されます)。名前をさらに省略しないでください。AWS の主要コンポーネント (VPC や ELB など) のよく知られた省略形である場合は問題ありませんが、新しい名前を個別に作成しないでください。

en: Unless the name of your service is quite unique, please consider using ``aws_`` as a prefix. For example ``aws_lambda``.
ja: サービスの名前が非常に一意でない限り、``aws_`` をプレフィックスとして使用することを検討してください。たとえば、``aws_lambda`` となります。

en: Importing botocore and boto3
ja: botocore および boto3 のインポート

en: The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and ``ansible_collections.amazon.aws.plugins.module_utils.core`` modules both automatically import boto3 and botocore.  If boto3 is missing from the system then the variable ``HAS_BOTO3`` will be set to false.  Normally, this means that modules don't need to import boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule as the module does that check:
ja: ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` モジュールと ``ansible_collections.amazon.aws.plugins.module_utils.core`` モジュールは、boto3 と botocore を自動的にインポートします。 システムに boto3 がない場合は、変数 ``HAS_BOTO3`` が false に設定されます。通常、これは、boto3 を直接インポートする必要はありません。AnsibleAWSModule を使用する場合は、モジュールが ``HAS_BOTO3`` を確認するため、その確認を行う必要はありません。

en: or:
ja: または

en: Supporting Module Defaults
ja: モジュールのデフォルトのサポート

en: The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common authentication parameters.  To do the same for your new module, add an entry for it in ``meta/runtime.yml``.  These entries take the form of:
ja: 既存の AWS モジュールは、共通の認証パラメーターに :ref:`module_defaults <module_defaults>` を使用することをサポートします。新しいモジュールに同じことを行うには、``meta/runtime.yml`` でエントリーを追加します。これらのエントリーは以下の形式になります。

en: Connecting to AWS
ja: AWS への接続

en: AnsibleAWSModule provides the ``resource`` and ``client`` helper methods for obtaining boto3 connections. These handle some of the more esoteric connection options, such as security tokens and boto profiles.
ja: AnsibleAWSModule は、boto3 接続を取得するためのヘルパーメソッド ``resource`` および ``client`` を提供します。これらは、セキュリティートークンや boto プロファイルなど、より難解な接続オプションのいくつかを処理します。

en: If using the basic AnsibleModule then you should use ``get_aws_connection_info`` and then ``boto3_conn`` to connect to AWS as these handle the same range of connection options.
ja: 接続オプションと同じ範囲を処理するため、基本的な AnsibleModule を使用する場合は、``get_aws_connection_info`` を使用してから ``boto3_conn`` を使用して AWS に接続する必要があります。

en: These helpers also for missing profiles or a region not set when it needs to be, so you don't have to.
ja: これらのヘルパーは、欠落しているプロファイルや、必要なときに設定されていない領域にも使用できるため、必須ではありません。

en: An example of connecting to ec2 is shown below. Note that unlike boto there is no ``NoAuthHandlerFound`` exception handling like in boto. Instead, an ``AuthFailure`` exception will be thrown when you use the connection. To ensure that authorization, parameter validation and permissions errors are all caught, you should catch ``ClientError`` and ``BotoCoreError`` exceptions with every boto3 connection call. See exception handling:
ja: ec2 への接続例は以下のようになります。boto とは異なり、boto には、``NoAuthHandlerFound`` の例外処理がないことに注意してください。代わりに、接続の使用時に ``AuthFailure`` 例外が出力されます。承認、パラメーター検証、およびパーミッションエラーがすべて取得されるようにするには、すべての boto3 接続呼び出しで ``ClientError`` および ``BotoCoreError`` の例外を取得する必要があります。「例外処理」を参照してください。

en: or for the higher level ec2 resource:
ja: また、より高いレベルの ec2 リソースの場合は、次のようになります。

en: An example of the older style connection used for modules based on AnsibleModule rather than AnsibleAWSModule:
ja: AnsibleAWSModule ではなく AnsibleModule に基づくモジュールに使用される旧式の接続例は次のとおりです。

en: Common Documentation Fragments for Connection Parameters
ja: 接続パラメーターに関する断片化された汎用ドキュメント

en: There are two :ref:`common documentation fragments <module_docs_fragments>` that should be included into almost all AWS modules:
ja: ほとんどすべての AWS モジュールに含まれる :ref:`断片化された汎用ドキュメント <module_docs_fragments>` は 2 つあります。

en: ``aws`` - contains the common boto connection parameters
ja: ``aws`` - 共通の boto 接続パラメーターが含まれます。

en: ``ec2`` - contains the common region parameter required for many AWS modules
ja: ``ec2`` - 多数の AWS モジュールに必要な共通の region パラメーターが含まれます。

en: These fragments should be used rather than re-documenting these properties to ensure consistency and that the more esoteric connection options are documented. For example:
ja: 一貫性を確保し、より難解な接続オプションを文書化するために、これらのプロパティーを再文書化するのではなく、これらのフラグメントを使用する必要があります。以下に例を示します。

en: Handling exceptions
ja: 例外の処理

en: You should wrap any boto3 or botocore call in a try block. If an exception is thrown, then there are a number of possibilities for handling it.
ja: try ブロックで boto3 または botocore 呼び出しをラップする必要があります。例外が出力された場合、それを処理するためのさまざまな可能性があります。

en: Catch the general ``ClientError`` or look for a specific error code with
ja: 汎用的な ``ClientError`` を取得するか、次のような特定のエラーコードを探します

en: Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way
ja: ``aws_module.fail_json_aws()`` を使用して、標準的な方法でモジュールの障害を報告します。

en: Retry using AWSRetry
ja: AWSRetry を使用して再試行します。

en: Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plugins.module_utils.core``
ja: ``fail_json()`` を使用して、``ansible_collections.amazon.aws.plugins.module_utils.core`` を使用せずに障害を報告します。

en: Do something custom in the case where you know how to handle the exception
ja: 例外の処理方法が分かっている場合は、なんらかのカスタマイズ作業を行います。

en: For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_.
ja: botocore 例外処理の詳細は、`botocore エラードキュメント <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_ を参照してください。

en: Using is_boto3_error_code
ja: is_boto3_error_code の使用

en: To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to catch a single AWS error code, call it in place of ``ClientError`` in your except clauses. In this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here, and any other error will be raised for handling elsewhere in the program.
ja: ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` を使用して単一の AWS エラーコードを取得するには、except 句で ``ClientError`` の代わりに呼び出しを行います。この場合、``InvalidGroup.NotFound`` エラーコードをここに検出し、その他のエラーでプログラム内の別の場所を処理する際に発生します。

en: Using fail_json_aws()
ja: fail_json_aws() の使用

en: In the AnsibleAWSModule there is a special method, ``module.fail_json_aws()`` for nice reporting of exceptions.  Call this on your exception and it will report the error together with a traceback for use in Ansible verbose mode.
ja: AnsibleAWSModule には、例外をレポートするのに優れたメソッド ``module.fail_json_aws()`` があります。例外上でこの呼び出しを行い、Ansible の冗長モードで使用するためにトレースバックと共にエラーを報告します。

en: You should use the AnsibleAWSModule for all new modules, unless not possible. If adding significant amounts of exception handling to existing modules, we recommend migrating the module to use AnsibleAWSModule (there are very few changes required to do this)
ja: 不可能でない限り、すべての新しいモジュールに AnsibleAWSModule を使用する必要があります。既存のモジュールに大量の例外処理を追加する場合は、AnsibleAWSModule を使用するようにモジュールを移行することが推奨されます (これを行うために必要な変更はほとんどありません)。

en: Note that it should normally be acceptable to catch all normal exceptions here, however if you expect anything other than botocore exceptions you should test everything works as expected.
ja: 通常、ここですべての通常の例外を捕えても問題がないことに注意してください。ただし、botocore 以外の例外が予想される場合は、すべてが期待どおりに機能するかどうかをテストする必要があります。

en: If you need to perform an action based on the error boto3 returned, use the error code and the ``is_boto3_error_code()`` helper.
ja: 返された boto3 エラーに基づいてアクションを実行する必要がある場合は、このエラーコードおよび ``is_boto3_error_code()`` ヘルパーを使用します。

en: Boto3 provides lots of useful information when an exception is thrown so pass this to the user along with the message.
ja: Boto3 は、例外が発生したときに多くの有用な情報を提供するため、メッセージと共にこれをユーザーに渡します。

en: Note: we use `str(e)` rather than `e.message` as the latter doesn't work with python3
ja: 注記: `e.message` は python3 では機能しないため、代わりに `str(e)` を使用します。

en: If you need to perform an action based on the error boto3 returned, use the error code.
ja: 返された boto3 エラーに基づいてアクションを実行する必要がある場合は、このエラーコードを使用します。

en: API throttling (rate limiting) and pagination
ja: API スロットリング (レート制限) とページネーション

en: For methods that return a lot of results, boto3 often provides `paginators <https://boto3.readthedocs.io/en/latest/guide/paginators.html>`_. If the method you're calling has ``NextToken`` or ``Marker`` parameters, you should probably check whether a paginator exists (the top of each boto3 service reference page has a link to Paginators, if the service has any). To use paginators, obtain a paginator object, call ``paginator.paginate`` with the appropriate arguments and then call ``build_full_result``.
ja: 大量の結果を返すメソッドの場合、boto3 はしばしば `paginators <https://boto3.readthedocs.io/en/latest/guide/paginators.html>`_ を提供します。呼び出しているメソッドに ``NextToken`` パラメーターまたは ``Marker`` パラメーターがある場合は、Paginator が存在するかどうかを確認する必要があります (各 boto3 サービスに Paginator がある場合は、参照ページ上部に Paginator へのリンクがあります)。Paginator を使用するには、Paginator オブジェクトを取得し、適切な引数を指定して ``paginator.paginate`` を呼び出してから、``build_full_result`` を呼び出します。

en: Any time that you are calling the AWS API a lot, you may experience API throttling, and there is an ``AWSRetry`` decorator that can be used to ensure backoff. Because exception handling could interfere with the retry working properly (as AWSRetry needs to catch throttling exceptions to work correctly), you'd need to provide a backoff function and then put exception handling around the backoff function.
ja: AWS API を大量に呼び出しているのはいつでも、API スロットリングが発生する可能性があり、バックオフ機能を提供するために使用できる ``AWSRetry`` デコレーターがあります。例外処理は再試行が正しく機能するのを妨げる可能性があるため (AWSRetry が正しく機能するためにスロットリング例外を取得する必要があるため)、バックオフ関数を提供してから、バックオフ関数の周りに例外処理を置く必要があります。

en: You can use ``exponential_backoff`` or ``jittered_backoff`` strategies - see the cloud ``module_utils`` ()/lib/ansible/module_utils/cloud.py) and `AWS Architecture blog <https://www.awsarchitectureblog.com/2015/03/backoff.html>`_ for more details.
ja: ``exponential_backoff`` ストラテジーまたは ``jittered_backoff`` ストラテジーを使用できます。詳細は、クラウド ``module_utils`` ()/lib/ansible/module_utils/cloud.py) および `AWS アーキテクチャーのブログ <https://www.awsarchitectureblog.com/2015/03/backoff.html>`_ を参照してください。

en: The combination of these two approaches is then:
ja: これら 2 つのアプローチの組み合わせは次のとおりです。

en: Prior to Ansible 2.10 if the underlying ``describe_some_resources`` API call threw a ``ResourceNotFound`` exception, ``AWSRetry`` would take this as a cue to retry until it is not thrown (this is so that when creating a resource, we can just retry until it exists).  This default was changed and it is now necessary to explicitly request this behaviour.  This can be done by using the ``catch_extra_error_codes`` argument on the decorator.
ja: Ansible 2.10 より前のバージョンでは、基盤となる ``describe_some_resources`` API コールが ``ResourceNotFound`` 例外を出力した場合、``AWSRetry`` は、これが出力されなくなるまで再試行する合図とみなしています (これは、リソースを作成する際に、リソースが存在するまで再試行できるようにするためです)。このデフォルトが変更になり、現在ではこの動作を明示的に要求する必要があります。これを行うには、デコレーターの ``catch_extra_error_codes`` 引数を使用します。

en: To make use of AWSRetry easier, it can now be wrapped around a client returned by ``AnsibleAWSModule``. any call from a client. To add retries to a client, create a client:
ja: AWSRetry を使いやすくするために、``AnsibleAWSModule`` (クライアントからの呼び出し) によって返されたクライアントをラップできるようになりました。クライアントに再試行を追加するには、クライアントを作成します。

en: Any calls from that client can be made to use the decorator passed at call-time using the `aws_retry` argument. By default, no retries are used.
ja: そのクライアントからの呼び出しはすべて、`aws_retry` 引数を使用して呼び出し時に渡されたデコレーターを使用して行うことができます。デフォルトでは、再試行は使用されません。

en: The call will be retried the specified number of times, so the calling functions don't need to be wrapped in the backoff decorator.
ja: 呼び出しは指定された回数だけ再試行されるため、呼び出し元の関数をバックオフデコレーターでラップする必要はありません。

en: You can also use customization for ``retries``, ``delay`` and ``max_delay`` parameters used by ``AWSRetry.jittered_backoff`` API using module params. You can take a look at the `cloudformation <cloudformation_module>` module for example.
ja: また、モジュールパラメーターを使用して、``AWSRetry.jittered_backoff`` API が使用する ``retries`` パラメーター、``delay`` パラメーター、および ``max_delay`` パラメーターのカスタマイズを使用することもできます。たとえば、`cloudformation <cloudformation_module>` モジュールを参照してください。

en: To make all Amazon modules uniform, prefix the module param with ``backoff_``, so ``retries`` becomes ``backoff_retries``
ja: すべての Amazon モジュールを均一にするには、モジュールパラメーターの前に ``backoff_`` を付けます。これにより、``retries`` は ``backoff_retries`` になります。

en: and likewise with ``backoff_delay`` and ``backoff_max_delay``.
ja: ``backoff_delay`` と ``backoff_max_delay`` も同様です。

en: Returning Values
ja: 戻り値

en: When you make a call using boto3, you will probably get back some useful information that you should return in the module.  As well as information related to the call itself, you will also have some response metadata.  It is OK to return this to the user as well as they may find it useful.
ja: boto3 を使用して呼び出しを行うと、モジュールで返す必要がある便利な情報を入手できます。また、呼び出し自体に関連する情報や応答メタデータもあります。これをユーザーに返すことは問題ありません。ユーザーにそれが役に立つと思うかもしれません。

en: Boto3 returns all values CamelCased.  Ansible follows Python standards for variable names and uses snake_case. There is a helper function in module_utils/ec2.py called `camel_dict_to_snake_dict` that allows you to easily convert the boto3 response to snake_case.
ja: boto3 は、CamelCase 化したすべての値を返します。Ansible は変数名の Python 標準に従い、snake_case を使用します。`camel_dict_to_snake_dict` という名前の module_utils/ec2.py にヘルパー関数があり、boto3 応答を簡単に snake_case に変換できます。

en: You should use this helper function and avoid changing the names of values returned by Boto3. E.g. if boto3 returns a value called 'SecretAccessKey' do not change it to 'AccessKey'.
ja: このヘルパー関数を使用し、Boto3 が返す値の名前を変更しないでください。たとえば、boto3 が「SecretAccessKey」値を返す場合は、これを「AccessKey」に変更しないでください。

en: Dealing with IAM JSON policy
ja: IAM JSON ポリシーの処理

en: If your module accepts IAM JSON policies then set the type to 'json' in the module spec. For example:
ja: モジュールが IAM JSON ポリシーを受け入れる場合は、モジュール仕様でタイプを「json」に設定します。たとえば、以下のようになります。

en: Note that AWS is unlikely to return the policy in the same order that is was submitted. Therefore, use the `compare_policies` helper function which handles this variance.
ja: AWS が、送信された順序でポリシーを返すことはほとんどありません。したがって、この差異を処理する `compare_policies` ヘルパー関数を使用します。

en: `compare_policies` takes two dictionaries, recursively sorts and makes them hashable for comparison and returns True if they are different.
ja: `compare_policies` は、2 つのディクショナリーを取得し、再帰的にソートし、比較のためにハッシュを可能にし、異なる場合は True を返します。

en: Dealing with tags
ja: タグの処理

en: AWS has a concept of resource tags. Usually the boto3 API has separate calls for tagging and untagging a resource.  For example, the ec2 API has a create_tags and delete_tags call.
ja: AWS にはリソースタグの概念があります。通常、boto3 API には、リソースのタグ付けとタグ付け解除のための呼び出しがあります。たとえば、ec2 API には create_tags および delete_tags の呼び出しがあります。

en: It is common practice in Ansible AWS modules to have a `purge_tags` parameter that defaults to true.
ja: これは、デフォルトが true の `purge_tags` パラメーターがある Ansible AWS モジュールでは一般的な方法です。

en: The `purge_tags` parameter means that existing tags will be deleted if they are not specified by the Ansible task.
ja: `purge_tags` パラメーターは、既存のタグが Ansible タスクで指定されていない場合に削除されることを示しています。

en: There is a helper function `compare_aws_tags` to ease dealing with tags. It can compare two dicts and return the tags to set and the tags to delete.  See the Helper function section below for more detail.
ja: タグの扱いを容易にするためヘルパー機能 `compare_aws_tags` があります。2 つのディクショナリーを比較し、設定するタグと削除するタグを返すことができます。詳細については、以下のヘルパー関数のセクションを参照してください。

en: Helper functions
ja: helper 関数

en: Along with the connection functions in Ansible ec2.py module_utils, there are some other useful functions detailed below.
ja: Ansible ec2.py モジュールユーティリティーの接続関数に加えて、以下に説明するいくつかの便利な関数があります。

en: boto3 returns results in a dict.  The keys of the dict are in CamelCase format. In keeping with Ansible format, this function will convert the keys to snake_case.
ja: boto3 はディクショナリーの結果を返します。ディクショナリーのキーは CamelCase 形式になります。Ansible 形式を維持すると、この機能はキーを snake_case に変換します。

en: ``camel_dict_to_snake_dict`` takes an optional parameter called ``ignore_list`` which is a list of keys not to convert (this is usually useful for the ``tags`` dict, whose child keys should remain with case preserved)
ja: ``camel_dict_to_snake_dict`` は、``ignore_list`` 呼ばれる任意のパラメーターを取ります。これは、変換しないキーの一覧です。これは通常、``tags`` ディクショナリーに役に立ちます。この子キーは大文字と小文字を区別して保持する必要があります。

en: Another optional parameter is ``reversible``. By default, ``HTTPEndpoint`` is converted to ``http_endpoint``, which would then be converted by ``snake_dict_to_camel_dict`` to ``HttpEndpoint``. Passing ``reversible=True`` converts HTTPEndpoint to ``h_t_t_p_endpoint`` which converts back to ``HTTPEndpoint``.
ja: その他の任意のパラメーターは ``reversible`` です。デフォルトでは、``HTTPEndpoint`` は ``http_endpoint`` に変換されます。これは、``snake_dict_to_camel_dict`` によって ``HttpEndpoint`` に変換されます。``reversible=True`` を渡すと、HTTPEndpoint が ``h_t_t_p_endpoint`` に変換され、``HTTPEndpoint`` に変換され直されます。

en: `snake_dict_to_camel_dict` converts snake cased keys to camel case. By default, because it was first introduced for ECS purposes, this converts to dromedaryCase. An optional parameter called `capitalize_first`, which defaults to `False`, can be used to convert to CamelCase.
ja: `snake_dict_to_camel_dict` は、スネークケースのキーをキャメルケースに変換します。デフォルトでは、ECS の目的で最初に導入されたため、これは dromedaryCase に変換されます。`capitalize_first` と呼ばれる任意のパラメーターは、`False` にデフォルトされ、CamelCase への変換に使用できます。

en: Converts a an Ansible list of filters to a boto3 friendly list of dicts.  This is useful for any boto3 `_facts` modules.
ja: フィルターの Ansible リストを、ディクショナリーの boto3 フレンドリーリストに変換します。これは、boto3 の `_facts` モジュールに役立ちます。

en: Pass an exception returned from boto or boto3, and this function will consistently get the message from the exception.
ja: boto または boto3 から返された例外を渡します。この関数は、例外からメッセージを一貫して取得します。

en: Deprecated: use `AnsibleAWSModule`'s `fail_json_aws` instead.
ja: 非推奨: 代わりに `AnsibleAWSModule` の `fail_json_aws` を使用してください。

en: Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containing keys called 'Key' and 'Value' by default.  This key names can be overridden when calling the function. For example, if you have already camel_cased your list of tags you may want to pass lowercase key names instead, in other words, 'key' and 'value'.
ja: boto3 タグリストを Ansible ディクショナリーに変換します。Boto3 は、「Key」および「Value」という名前のキーがデフォルトで含まれる ディクショナリーのリストとしてタグを返します。このキーは、関数を呼び出す際に上書きできます。たとえば、タグのリストをすでにキャメルケース化している場合は、代わりに小文字のキー名、つまり「key」と「value」を渡すことができます。

en: This function converts the list in to a single dict where the dict key is the tag key and the dict value is the tag value.
ja: この関数は、リストを単一のディクショナリーに変換します。dic キーはtag キーで、ディクショナリーの値はタグの値です。

en: Opposite of above. Converts an Ansible dict to a boto3 tag list of dicts. You can again override the key names used if 'Key' and 'Value' is not suitable.
ja: 上記の逆で、Ansible ディクショナリーをディクショナリーの boto3 タグ一覧に変換します。「Key」と「Value」が適していない場合に使用されるキー名を再度上書きすることもできます。

en: Pass this function a list of security group names or combination of security group names and IDs and this function will return a list of IDs.  You should also pass the VPC ID if known because security group names are not necessarily unique across VPCs.
ja: この関数にセキュリティーグループ名のリスト、またはセキュリティーグループ名と ID の組み合わせを渡すと、この関数は ID のリストを返します。セキュリティーグループ名は VPC 間で必ずしも一意であるとは限らないため、既知の場合は VPCID も渡す必要があります。

en: Pass two dicts of policies to check if there are any meaningful differences and returns true if there are. This recursively sorts the dicts and makes them hashable before comparison.
ja: ポリシーの 2 つのディクショナリーを渡して、意味のある差異があるかどうかを確認し、ある場合は true を返します。これにより、ディクショナリーが再帰的にソートされ、比較前にハッシュ可能になります。

en: This method should be used any time policies are being compared so that a change in order doesn't result in unnecessary changes.
ja: この方法は、順序を変更しても不要な変更が発生しないように、ポリシーを比較するときに必ず使用する必要があります。

en: Pass two dicts of tags and an optional purge parameter and this function will return a dict containing key pairs you need to modify and a list of tag key names that you need to remove.  Purge is True by default.  If purge is False then any existing tags will not be modified.
ja: タグの 2 つのディクショナリーと任意の purge パラメーターを渡します。この関数はディクショナリーを返します。これには、変更する必要があるキーペアと、削除する必要のあるタグキー名の一覧が含まれています。パージは、デフォルトで True です。パージが False の場合は、既存のタグが変更されません。

en: This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to use the other helper function `boto3_tag_list_to_ansible_dict` to get an appropriate tag dict before calling this function. Since the AWS APIs are not uniform (for example, EC2 is different from Lambda) this will work without modification for some (Lambda) and others may need modification before using these values (such as EC2, with requires the tags to unset to be in the form `[{'Key': key1}, {'Key': key2}]`).
ja: この関数は、boto3 の「add_tags」関数および「remove_tags」関数を使用する場合に役に立ちます。この関数を呼び出す前に、必ず他のヘルパー関数 `boto3_tag_list_to_ansible_dict` を使用して、適切なタグのディクショナリーを取得してください。AWS の API は統一されていないため (たとえば、EC2 と Lambda は異なります)、一部 (Lambda) では修正なしで動作しますが、これらの値を使用する前に修正が必要な場合がありますも (EC2 では、設定解除するタグを `[{'Key': key1}, {'Key': key2}]` の形式にする必要があるなど)。

en: Integration Tests for AWS Modules
ja: AWS モジュールの統合テスト

en: All new AWS modules should include integration tests to ensure that any changes in AWS APIs that affect the module are detected. At a minimum this should cover the key API calls and check the documented return values are present in the module result.
ja: すべての新規 AWS モジュールには、モジュールに影響する AWS API の変更が検出されるように、統合テストを含める必要があります。最小値はキー API 呼び出しに対応し、文書化された戻り値がモジュールの結果に存在するようにする必要があります。

en: For general information on running the integration tests see the :ref:`Integration Tests page of the Module Development Guide <testing_integration>`, especially the section on configuration for cloud tests.
ja: 統合テストの実行に関する一般的な情報は、:ref:`モジュール開発ガイドの統合テストページ <testing_integration>` ページ (特に、クラウドテスト設定のセクション) を参照してください。

en: The integration tests for your module should be added in `test/integration/targets/MODULE_NAME`.
ja: モジュールの統合テストは、`test/integration/targets/MODULE_NAME` に追加する必要があります。

en: You must also have a aliases file in `test/integration/targets/MODULE_NAME/aliases`. This file serves two purposes. First indicates it's in an AWS test causing the test framework to make AWS credentials available during the test run. Second putting the test in a test group causing it to be run in the continuous integration build.
ja: また、`test/integration/targets/MODULE_NAME/aliases` にはエイリアスファイルが必要です。このファイルには 2 つの目的があります。最初に、それが AWS テストにあり、テストフレームワークがテスト実行中に AWS 認証情報を利用できるようにしていることを示します。次に、テストをテストグループに入れて、継続的統合ビルドで実行します。

en: Tests for new modules should be added to the same group as existing AWS tests. In general just copy an existing aliases file such as the `aws_s3 tests aliases file <https://github.com/ansible-collections/amazon.aws/blob/master/tests/integration/targets/aws_s3/aliases>`_.
ja: 新規モジュールのテストは、既存の AWS テストと同じグループに追加する必要があります。一般に、`aws_s3 テストエイリアスファイル <https://github.com/ansible-collections/amazon.aws/blob/master/tests/integration/targets/aws_s3/aliases>`_ のような既存のエイリアスファイルをコピーするだけです。

en: AWS Credentials for Integration Tests
ja: 統合テストの AWS 認証情報

en: The testing framework handles running the test with appropriate AWS credentials, these are made available to your test in the following variables:
ja: テストフレームワークは、適切な AWS 認証情報を使用したテストの実行を処理します。この認証情報は、次の変数で、テストに利用できます。

en: So all invocations of AWS modules in the test should set these parameters. To avoid duplicating these for every call, it's preferable to use :ref:`module_defaults <module_defaults>`. For example:
ja: したがって、テストで AWS モジュールを呼び出す場合はすべて、これらのパラメーターを設定する必要があります。呼び出しごとにこれらが重複しないようにするには、:ref:`module_defaults <module_defaults>` を使用することが推奨されます。以下に例を示します。

en: AWS Permissions for Integration Tests
ja: 統合テスト用の AWS パーミッション

en: As explained in the :ref:`Integration Test guide <testing_integration>` there are defined IAM policies in `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ that contain the necessary permissions to run the AWS integration test.
ja: :ref:`Integration Test guide <testing_integration>` で説明されているように、AWS 統合テストを実行するために必要な権限が含まれる `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ で定義された IAM ポリシーがあります。

en: If your module interacts with a new service or otherwise requires new permissions, tests will fail when you submit a pull request and the `Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ will tag your PR as needing revision. We do not automatically grant additional permissions to the roles used by the continuous integration builds. You will need to raise a Pull Request against `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ to add them.
ja: モジュールが新しいサービスとやり取りする場合、または別の方法で新しいパーミッションが必要な場合は、プル要求を送信すると、テストは失敗します。`Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ は、PR に修正が必要なタグを付けます。継続的インテグレーションビルドで使用されるロールに追加のパーミッションを自動的に付与することはありません。それを追加するには、`mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ に対してプル要求を発行する必要があります、それらを追加します。

en: If your PR has test failures, check carefully to be certain the failure is only due to the missing permissions. If you've ruled out other sources of failure, add a comment with the `ready_for_review` tag and explain that it's due to missing permissions.
ja: PR にテストの失敗がある場合は、失敗の原因がパーミッションの欠落のみであることをしっかりと確認してください。他の失敗の原因を除外した場合は、`ready_for_review` タグを使用してコメントを追加して、権限がないことが原因であることを説明します。

en: Your pull request cannot be merged until the tests are passing. If your pull request is failing due to missing permissions, you must collect the minimum IAM permissions required to run the tests.
ja: テストに合格するまでプル要求がマージできません。パーミッションがないためにプル要求が失敗すると、テストの実行に必要な最低限の IAM パーミッションを収集する必要があります。

en: There are two ways to figure out which IAM permissions you need for your PR to pass:
ja: PR に合格するために必要な IAM パーミッションを確認する場合は、以下の 2 つの方法があります。

en: Start with the most permissive IAM policy, run the tests to collect information about which resources your tests actually use, then construct a policy based on that output. This approach only works on modules that use `AnsibleAWSModule`.
ja: 最も許容度の高い IAM ポリシーから始めて、テストを実行し、テストが実際に使用するリソースに関する情報を収集し、その出力に基づいてポリシーを構築します。このアプローチは、`AnsibleAWSModule` を使用するモジュールでのみ機能します。

en: Start with the least permissive IAM policy, run the tests to discover a failure, add permissions for the resource that addresses that failure, then repeat. If your module uses `AnsibleModule` instead of `AnsibleAWSModule`, you must use this approach.
ja: 最も許容度の低い IAM ポリシーから開始し、テストを実行して障害を検出し、その障害に対処するリソースのパーミッションを追加してから、繰り返します。モジュールが、`AnsibleAWSModule` の代わりに `AnsibleModule` を使用する場合は、このアプローチを使用する必要があります。

en: To start with the most permissive IAM policy:
ja: 最も許容度の高い IAM ポリシーを使用するには、以下を実行します。

en: `Create an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_ that allows all actions (set ``Action`` and ``Resource`` to ``*```).
ja: すべてのアクションを許可する `IAM ポリシーを作成 <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_ します (``Action`` および ``Resource`` を ``*``' に設定)。

en: Run your tests locally with this policy. On AnsibleAWSModule-based modules, the ``debug_botocore_endpoint_logs`` option is automatically set to ``yes``, so you should see a list of AWS ACTIONS after the PLAY RECAP showing all the permissions used. If your tests use a boto/AnsibleModule module, you must start with the least permissive policy (see below).
ja: このポリシーを使用して、ローカルでテストを実行します。AnsibleAWSModule ベースのモジュールでは、``debug_botocore_endpoint_logs`` オプションが自動的に ``yes`` に設定されます。したがって、PLAY RECAP の後に、使用されているすべてのパーミッションを示す AWS ACTIONS のリストが表示されます。テストで boto/AnsibleModule モジュールを使用する場合は、最も許容度の低いポリシーから開始する必要があります (以下を参照)。

en: Modify your policy to allow only the actions your tests use. Restrict account, region, and prefix where possible. Wait a few minutes for your policy to update.
ja: テストで使用するアクションのみを許可するようにポリシーを変更します。可能な場合は、アカウント、地域、プレフィックスを制限してください。ポリシーが更新されるまで数分待ちます。

en: Run the tests again with a user or role that allows only the new policy.
ja: 新規ポリシーのみを許可するユーザーまたはロールでテストを再実行します。

en: If the tests fail, troubleshoot (see tips below), modify the policy, run the tests again, and repeat the process until the tests pass with a restrictive policy.
ja: テストに失敗し、トラブルシューティング (以下のヒントを参照) を行い、ポリシーを変更し、テストを再実行し、制限的なポリシーでテストに合格するまでプロセスを繰り返します。

en: Open a pull request proposing the minimum required policy to the `CI policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_.
ja: `CI ポリシー <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_ に対して最低限必要なポリシーを提案するプル要求を開きます。

en: To start from the least permissive IAM policy:
ja: 最も許容度の低い IAM ポリシーから開始するには、以下を実行します。

en: Run the integration tests locally with no IAM permissions.
ja: IAM パーミッションを使用せずにローカルの統合テストを実行します。

en: Examine the error when the tests reach a failure.
ja: テストが失敗した場合はエラーを確認します。

en: If the error message indicates the action used in the request, add the action to your policy.
ja: エラーメッセージがリクエストで使用されるアクションを示す場合は、アクションをポリシーに追加します。

en: If the error message does not indicate the action used in the request:
ja: エラーメッセージがリクエストで使用されるアクションを示していない場合は、以下を行います。

en: Usually the action is a CamelCase version of the method name - for example, for an ec2 client the method `describe_security_groups` correlates to the action `ec2:DescribeSecurityGroups`.
ja: 通常、アクションはメソッド名の CamelCase バージョンです。たとえば、ec2 クライアントの場合、`describe_security_groups` メソッドはアクション `ec2:DescribeSecurityGroups` に相関します。

en: Refer to the documentation to identify the action.
ja: アクションを特定するには、ドキュメントを参照してください。

en: If the error message indicates the resource ARN used in the request, limit the action to that resource.
ja: エラーメッセージが要求で使用されるリソース ARN を示す場合は、アクションをそのリソースに制限します。

en: If the error message does not indicate the resource ARN used:
ja: エラーメッセージに、使用されたリソース ARN が示されない場合は、以下を行います。

en: Determine if the action can be restricted to a resource by examining the documentation.
ja: ドキュメントを参照して、アクションをリソースに制限できるかどうかを判断します。

en: If the action can be restricted, use the documentation to construct the ARN and add it to the policy.
ja: アクションが制限されている場合は、ドキュメントを使用して ARN を構築し、ポリシーに追加します。

en: Add the action or resource that caused the failure to `an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_. Wait a few minutes for your policy to update.
ja: `IAM ポリシー <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_ の失敗の原因となったアクションまたはリソースを追加します。ポリシーが更新するまで数分待ちます。

en: Run the tests again with this policy attached to your user or role.
ja: ユーザーまたはロールにこのポリシーを割り当て、テストを再実行します。

en: If the tests still fail at the same place with the same error you will need to troubleshoot (see tips below). If the first test passes, repeat steps 2 and 3 for the next error. Repeat the process until the tests pass with a restrictive policy.
ja: それでも同じ場所、同じエラーでテストが失敗する場合は、トラブルシューティングを行う必要があります (以下のヒントを参照)。最初のテストに合格した場合は、次のエラーに対して手順 2 と 3 を繰り返します。制限付きポリシーでテストに合格するまで、このプロセスを繰り返します。

en: Troubleshooting IAM policies
ja: IAM ポリシーのトラブルシューティング

en: When you make changes to a policy, wait a few minutes for the policy to update before re-running the tests.
ja: ポリシーに変更を加えたら、ポリシーが更新されるまで数分待ってからテストを再実行します。

en: Use the `policy simulator <https://policysim.aws.amazon.com/>`_ to verify that each action (limited by resource when applicable) in your policy is allowed.
ja: `ポリシーシミュレーター <https://policysim.aws.amazon.com/>`_ を使用して、ポリシー内の (該当する場合はリソースによって制限されている) が許可されていることを確認します。

en: If you're restricting actions to certain resources, replace resources temporarily with `*`. If the tests pass with wildcard resources, there is a problem with the resource definition in your policy.
ja: 特定のリソースにアクションを制限する場合は、リソースを一時的に `*` に置き換えます。ワイルドカードリソースでテストに合格した場合は、ポリシーのリソース定義に問題があります。

en: If the initial troubleshooting above doesn't provide any more insight, AWS may be using additional undisclosed resources and actions.
ja: 上記の最初のトラブルシューティングでより多くの洞察が得られない場合、AWS は追加の非公開のリソースおよびアクションを使用している可能性があります。

en: Examine the AWS FullAccess policy for the service for clues.
ja: 手がかりについては、サービスの AWS FullAccess ポリシーを調べます。

en: Re-read the AWS documentation, especially the list of `Actions, Resources and Condition Keys <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html>`_ for the various AWS services.
ja: 各種の AWS サービスの「`Actions, Resources and Condition Keys <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html>`_」の一覧など、AWS ドキュメントを再度読みます。

en: Look at the `cloudonaut <https://iam.cloudonaut.io>`_ documentation as a troubleshooting cross-reference.
ja: トラブルシューティングの相互参照として `cloudonaut <https://iam.cloudonaut.io>`_ ドキュメントをご覧ください。

en: Use a search engine.
ja: 検索エンジンを使用します。

en: Ask in the Ansible IRC channel #ansible-aws (on `irc.libera.chat <https://libera.chat>`_).
ja: `irc.libera.chat <https://libera.chat>`_ の Ansible IRC チャンネル #ansible-aws に問い合わせます。

en: Unsupported Integration tests
ja: サポート対象外の統合テスト

en: There are a limited number of reasons why it may not be practical to run integration tests for a module within CI.  Where these apply you should add the keyword `unsupported` to the aliases file in `test/integration/targets/MODULE_NAME/aliases`.
ja: CI 内のモジュールの統合テストを実行することが実用的でない理由は限られています。これが当てはまる場合は、キーワード `unsupported` を `test/integration/targets/MODULE_NAME/aliases` のエイリアスファイルに追加する必要があります。

en: Some cases where tests should be marked as unsupported: 1) The tests take longer than 10 or 15 minutes to complete 2) The tests create expensive resources 3) The tests create inline policies 4) The tests require the existence of external resources 5) The tests manage Account level security policies such as the password policy or AWS Organizations.
ja: 1) テストが完了するまで 10 分または 15 分以上かかる場合。2) テストにより、高価なリソースが作成される場合。3) テストにより、インラインポリシーが作成される場合。4) テストに外部リソースの存在が必要になる場合。5) テストが、パスワードポリシーや AWS 組織などのアカウントレベルのセキュリティポリシーを管理する場合は、テストをサポート対象外としてマークを付ける必要があります。

en: Where one of these reasons apply you should open a pull request proposing the minimum required policy to the `unsupported test policies <https://github.com/mattclay/aws-terminator/tree/master/hacking/aws_config/test_policies>`_.
ja: 上記の理由の 1 つは、`サポート対象外のテストポリシー <https://github.com/mattclay/aws-terminator/tree/master/hacking/aws_config/test_policies>`_ に対して最低限必要なポリシーを提案するプル要求を開きます。

en: Unsupported integration tests will not be automatically run by CI.  However, the necessary policies should be available so that the tests can be manually run by someone performing a PR review or writing a patch.
ja: サポート対象外の統合テストは CI によって自動的に実行されませんが、必要なポリシーを利用すると、PR レビューまたはパッチの作成を実行してテストを手動で実行できるようにする必要があります。

en: OpenStack Ansible Modules
ja: OpenStack Ansible モジュール

en: Please see the `OpenStack guidelines <https://opendev.org/openstack/ansible-collections-openstack/src/branch/master/docs/openstack_guidelines.rst>`_,  for further information.
ja: 詳細は、`OpenStack ガイドライン <https://opendev.org/openstack/ansible-collections-openstack/src/branch/master/docs/openstack_guidelines.rst>`_ を参照してください。

en: oVirt Ansible Modules
ja: oVirt Ansible モジュール

en: The set of modules for interacting with oVirt/RHV are currently part of the community.general collection (on `Galaxy <https://galaxy.ansible.com/community/general>`_, source code `repository <https://github.com/ansible-collections/community.general/tree/main/plugins/modules/cloud/ovirt>`_). This document serves as developer coding guidelines for creating oVirt/RHV modules.
ja: oVirt/RHV との対話に使用するモジュールセットは、現在 community.general コレクション (`Galaxy <https://galaxy.ansible.com/community/general>`_ ではソースコード `repository <https://github.com/ansible-collections/community.general/tree/main/plugins/modules/cloud/ovirt>`_) に含まれます。このドキュメントは、oVirt/RHV モジュールを作成するための開発者コーディングのガイドラインとして機能します。

en: Naming
ja: 命名規則

en: All modules should start with an ``ovirt_`` prefix.
ja: すべてのモジュールは、``ovirt_`` プレフィックスで開始する必要があります。

en: All modules should be named after the resource it manages in singular form.
ja: すべてのモジュールは、管理するリソースにちなんで単数形で名前を付ける必要があります。

en: All modules that gather information should have a ``_info`` suffix.
ja: 情報を収集するすべてのモジュールには、``_info`` 構文があります。

en: Interface
ja: インターフェース

en: Every module should return the ID of the resource it manages.
ja: すべてのモジュールは、管理するリソースの ID を返す必要があります。

en: Every module should return the dictionary of the resource it manages.
ja: すべてのモジュールは、管理するリソースのディレクトリーを返す必要があります。

en: Never change the name of the parameter, as we guarantee backward compatibility. Use aliases instead.
ja: 後方互換性を保証するため、パラメーターの名前は変更しないでください。代わりにエイリアスを使用してください。

en: If a parameter can't achieve idempotency for any reason, please document it.
ja: パラメーターがなんらかの理由で冪等性を実現できない場合は、それを文書化してください。

en: Interoperability
ja: 相互運用性

en: All modules should work against all minor versions of version 4 of the API. Version 3 of the API is not supported.
ja: すべてのモジュールは API のバージョン 4 のすべてのマイナーバージョンに対して動作します。API のバージョン 3 はサポート対象外です。

en: Libraries
ja: ライブラリー

en: All modules should use ``ovirt_full_argument_spec`` or ``ovirt_info_full_argument_spec`` to pick up the standard input (such as auth and ``fetch_nested``).
ja: すべてのモジュールは ``ovirt_full_argument_spec`` または ``ovirt_info_full_argument_spec`` を使用して、標準入力 (認証、``fetch_nested`` など) にする必要があります。

en: All modules should use ``extends_documentation_fragment``: ovirt to go along with ``ovirt_full_argument_spec``.
ja: すべてのモジュールは、``ovirt_full_argument_spec`` に従うために ``extends_documentation_fragment``: ovirt を使用する必要があります。

en: All info modules should use ``extends_documentation_fragment``: ``ovirt_info`` to go along with ``ovirt_info_full_argument_spec``.
ja: すべての info モジュールは、``ovirt_info_full_argument_spec`` に従うために ``extends_documentation_fragment``: ``ovirt_info`` を使用する必要があります。

en: Functions that are common to all modules should be implemented in the ``module_utils/ovirt.py`` file, so they can be reused.
ja: すべてのモジュールに共通する関数は、``module_utils/ovirt.py`` ファイルに実装されているため、再利用できます。

en: Python SDK version 4 must be used.
ja: Python SDK バージョン 4 を使用する必要があります。

en: New module development
ja: 新しいモジュール開発

en: Please read :ref:`developing_modules`, first to know what common properties, functions and features every module must have.
ja: 「:ref:`developing_modules`」をお読みください。最初に、すべてのモジュールに必要な共通のプロパティー、関数、および機能を確認します。

en: In order to achieve idempotency of oVirt entity attributes, a helper class was created. The first thing you need to do is to extend this class and override a few methods:
ja: oVirt エンティティー属性のべき等性を実現するには、ヘルパークラスが作成されました。まず、このクラスを拡張し、いくつかのメソッドを上書きする必要があります。

en: The code above handle the check if the entity should be updated, so we don't update the entity if not needed and also it construct the needed entity of the SDK.
ja: 上記のコードは、エンティティーを更新すべきかどうかのチェックを処理するため、必要でない場合はエンティティーを更新せず、SDK に必要なエンティティーを構築します。

en: If your module must support action handling (for example, virtual machine start) you must ensure that you handle the states of the virtual machine correctly, and document the behavior of the module:
ja: モジュールがアクション処理 (例: 仮想マシンの開始) をサポートする必要がある場合は、仮想マシンの状態を正しく処理し、モジュールの動作を文書化する必要があります。

en: As you can see from the preceding example, the ``action`` method accepts the ``action_condition`` and ``wait_condition``, which are methods which accept the virtual machine object as a parameter, so you can check whether the virtual machine is in a proper state before the action. The rest of the parameters are for the ``start`` action. You may also handle pre- or post- action tasks by defining ``pre_action`` and ``post_action`` parameters.
ja: 前述の例で分かるように、``action`` メソッドは ``action_condition`` および ``wait_condition`` (仮想マシンオブジェクトをパラメーターとして許可するメソッド) を受け入れます。そのため、仮想マシンがアクションの前に適切な状態にあるかどうかを確認できます。残りのパラメーターは ``start`` アクション用です。``pre_action`` パラメーターおよび ``post_action`` パラメーターを定義して、事前または後続のアクションのタスクを処理することもできます。

en: Testing
ja: テスト

en: Integration testing is currently done in oVirt's CI system `on Jenkins <https://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__ and `on GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__.
ja: 統合テストは、現在、`Jenkins <https://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__ と `GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__ の oVirt's CI システムで行われています。

en: Please consider using these integration tests if you create a new module or add a new feature to an existing module.
ja: 新しいモジュールを作成する場合、または既存のモジュールに新しい機能を追加する場合は、これらの統合テストの使用を検討してください。

en: Guidelines for VMware module development
ja: VMware モジュール開発のガイドライン

en: The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, source code `repository <https://github.com/ansible-collections/community.vmware>`_) is maintained by the VMware Working Group. For more information see the `team community page <https://github.com/ansible/community/wiki/VMware>`_.
ja: 詳細は、Ansible VMware コレクション (`Galaxy <https://galaxy.ansible.com/community/vmware>`_ で、ソースコード `repository <https://github.com/ansible-collections/community.vmware>`_) は VMware ワーキンググループにより維持されます。詳細は `チームコミュニティーページ <https://github.com/ansible/community/wiki/VMware>`_ を参照してください。

en: Testing with govcsim
ja: govcsim を使用したテスト

en: Most of the existing modules are covered by functional tests. The tests are located `here <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets>`_.
ja: 既存のモジュールのほとんどは、機能テストで対応しています。テストは、`ここ <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets>`_ に置かれます。

en: By default, the tests run against a vCenter API simulator called `govcsim <https://github.com/vmware/govmomi/tree/master/vcsim>`_. ``ansible-test`` will automatically pull a `govcsim container <https://quay.io/repository/ansible/vcenter-test-container>`_ and use it to set-up the test environment.
ja: デフォルトでは、テストは、`govcsim <https://github.com/vmware/govmomi/tree/master/vcsim>`_ という名前の vCenter API シミュレーターに対して実行されます。``ansible-test`` は、`govcsim コンテナー <https://quay.io/repository/ansible/vcenter-test-container>`_ を自動的にプルし、これを使用してテスト環境を設定します。

en: You can trigger the test of a module manually with the ``ansible-test`` command. For example, to trigger ``vcenter_folder`` tests:
ja: ``ansible-test`` コマンドを使用して、モジュールのテストを手動でトリガーできます。たとえば、``vcenter_folder`` テストを開始するには、以下を行います。

en: ``govcsim`` is handy because it is much faster than a regular test environment. However, ``govcsim`` does not support all the ESXi or vCenter features.
ja: ``govcsim`` は、通常のテスト環境よりもはるかに高速ですが、``govcsim`` は ESXi 機能または vCenter 機能をすべてサポートしません。

en: Do not confuse ``govcsim`` with ``vcsim``. ``vcsim`` is an older and outdated version of vCenter simulator, whereas ``govcsim`` is new and written in Go language.
ja: ``govcsim`` と ``vcsim`` を混同しないでください。``vcsim`` は、古いバージョンの vCenterシミュレーターですが、``govcsim`` は新しく、Go 言語で書かれています

en: Testing with your own infrastructure
ja: 独自のインフラストラクチャーでのテスト

en: You can also target a regular VMware environment. This paragraph explains step by step how you can run the test-suite yourself.
ja: 通常の VMware 環境を対象とすることもできます。この段落では、テストスイートを自分で実行する方法について順を追って説明します。

en: 2 ESXi hosts (6.5 or 6.7)
ja: 2 台の ESXi ホスト (6.5 または 6.7)

en: with 2 NIC, the second ones should be available for the test
ja: 2 つの NIC (テスト用に 2 番目の NIC が利用可能)

en: a VCSA host
ja: VCSA ホスト

en: a NFS server
ja: NFS サーバー

en: Python dependencies:
ja: Python の依存関係:

en: If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https://github.com/goneri/vmware-on-libvirt>`_ works well.
ja: ハイパーバイザーにテスト環境をデプロイする場合は、`VMware または Libvirt <https://github.com/goneri/vmware-on-libvirt>` の両方が正常に機能します。

en: NFS server configuration
ja: NFS サーバーの設定

en: Your NFS server must expose the following directory structure:
ja: NFS サーバーでは、以下のディレクトリー構造を公開する必要があります。

en: On a Linux system, you can expose the directory over NFS with the following export file:
ja: Linux システムでは、次のエクスポートファイルを使用して、NFS 経由でディレクトリーを公開できます。

en: With this configuration all the new files will be owned by the user with the UID and GID 1000/1000. Adjust the configuration to match your user's UID/GID.
ja: この設定では、UID 1000 および GID 1000 のユーザーが、新しいファイルをすべて所有します。ユーザーの UID および GID に合わせて設定を調整してください。

en: The service can be enabled with:
ja: このサービスは以下で有効にできます。

en: Configure your installation
ja: インストールの設定

en: Prepare a configuration file that describes your set-up. The file should be called :file:`test/integration/cloud-config-vcenter.ini` and based on :file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with `vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_:
ja: セットアップを説明する構成ファイルを準備します。このファイルは :file:`test/integration/cloud-config-vcenter.ini` という名前し、:file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template` をベースにする必要があります。たとえば、`vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_ でラボをデプロイした場合は以下のようになります。

en: Using an HTTP proxy
ja: HTTP プロキシーの使用

en: Hosting test infrastructure behind an HTTP proxy is supported. You can specify the location of the proxy server with the two extra keys:
ja: HTTP プロキシーの背後にあるホスティングテストインフラストラクチャーがサポートされています。次の 2 つの追加キーを使用して、プロキシーサーバーの場所を指定できます。

en: In addition, you may need to adjust the variables of the following `var files <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ to match the configuration of your lab. If you use vmware-on-libvirt to prepare your lab, you do not have anything to change.
ja: さらに、ラボの構成に一致させるために、次の `var ファイル <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ の変数を調整しないといけない場合があります。vmware-on-libvirt を使用してラボを準備する場合は、変更することができません。

en: Run the test-suite
ja: テストスイートの実行

en: Once your configuration is ready, you can trigger a run with the following command:
ja: 設定の準備ができたら、以下のコマンドで実行をトリガーできます。

en: ``vmware_host_firewall_manager`` is the name of the module to test.
ja: ``vmware_host_firewall_manager`` は、テストするモジュールの名前です。

en: ``vmware_guest`` is much larger than any other test role and is rather slow. You can enable or disable some of its test playbooks in `main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_.
ja: ``vmware_guest`` は、他のテストロールよりもはるかに大きく、速度もかなり遅くなります。`main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_ でテスト Playbook の一部を有効または無効にできます。

en: Unit-test
ja: ユニットテスト

en: The VMware modules have limited unit-test coverage. You can run the test suite with the following commands:
ja: VMware モジュールでは、ユニットテストの範囲が限定されています。以下のコマンドを実行してテストスイートを実行できます。

en: Code style and best practice
ja: コードスタイルおよびベストプラクティス

en: datacenter argument with ESXi
ja: ESXi での datacenter 引数

en: The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because the user may not realize that Ansible silently targets the wrong data center.
ja: ``datacenter`` パラメーターはデフォルトで ``ha-datacenter`` を使用しないでください。これは、Ansible が間違ったデータセンターをサイレントにターゲットにしていることにユーザーが気付かない可能性があるためです。

en: esxi_hostname should not be mandatory
ja: esxi_hostname は必須ではない

en: Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly work with both. In this case, ``esxi_hostname`` parameter should be optional.
ja: ESXi または vCenter が提供する機能に応じて、一部のモジュールは両方でシームレスに動作します。この場合、``esxi_hostname`` パラメーターは任意である必要があります。

en: Example should use the fully qualified collection name (FQCN)
ja: 例では、完全修飾コレクション名 (FQCN) を使用する必要があります

en: Use FQCN for examples within module documentation. For instance, you should use ``community.vmware.vmware_guest`` instead of just ``vmware_guest``.
ja: モジュールドキュメントの例としては、FQCN を使用してください。たとえば、``vmware_guest`` ではなく ``community.vmware.vmware_guest`` を使用する必要があります。

en: This way, the examples do not depend on the ``collections`` directive of the playbook.
ja: この方法では、Playbook の ``collections`` ディレクティブに依存しません。

en: Functional tests
ja: 機能テスト

en: Writing new tests
ja: 新規テストの作成

en: If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyond the standard Ansible :ref:`integration testing<testing_integration>` process.
ja: 統合テストの新しいコレクションを作成している場合は、標準の Ansible の :ref:`統合テスト<testing_integration>` プロセス以外に注意すべき VMware 固有の事項がいくつかあります。

en: The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ role. The resources defined there are automatically created by importing that role at the start of your test:
ja: テストスイートは、`prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ ロールにある一般的な事前定義済みの変数のセットを使用します。ここに定義されたリソースは、テストの開始時にそのロールをインポートして自動的に作成されます。

en: This will give you a ready to use cluster, datacenter, datastores, folder, switch, dvswitch, ESXi hosts, and VMs.
ja: これにより、クラスター、データセンター、データストア、ディレクトリー、スイッチ、dvSwitch、ESXi ホスト、および仮想マシンを使用する準備が整います。

en: No need to create too much resources
ja: リソースを過剰に作成する必要なし

en: Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By avoiding it, you speed up the test execution and you simplify the clean up afterwards.
ja: 多くの場合、``with_items`` を使用して複数のリソースの作成を行う必要はありません。これを回避することで、テストの実行を迅速化して、後でクリーンアップを単純化できます。

en: VM names should be predictable
ja: 仮想マシン名は、名前で内容が予測できるものにする

en: If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or ``test_vm3``. This way it will be automatically clean up for you.
ja: テスト中に新しい仮想マシンを作成する必要がある場合は、``test_vm1``、``test_vm2``、または ``test_vm3`` を使用できます。このように、自動的にクリーンアップされます。

en: Avoid the common boiler plate code in your test playbook
ja: テスト Playbook で一般的な boilerplate コードを回避する

en: From Ansible 2.10, the test suite uses `modules_defaults`. This module allow us to preinitialize the following default keys of the VMware modules:
ja: Ansible 2.10 以降では、テストスイートは `modules_defaults` を使用します。このモジュールにより、以下の VMware モジュールのデフォルトキーを事前に初期化できます。

en: For example, the following block:
ja: たとえば、以下のブロックの場合:

en: should be simplified to just:
ja: 以下を単純化する必要があります。

en: Typographic convention
ja: 表記規則

en: Nomenclature
ja: 命名法

en: We try to enforce the following rules in our documentation:
ja: Ansible のドキュメントでは、次のルールを適用しています。

en: VMware, not VMWare or vmware
ja: VMware (VMWare または vmware ではありません)

en: ESXi, not esxi or ESXI
ja: ESXi (esxi または ESXI ではありません)

en: vCenter, not vcenter or VCenter
ja: vCenter (vcenter または VCenter ではありません)

en: We also refer to vcsim's Go implementation with ``govcsim``. This to avoid any confusion with the outdated implementation.
ja: また、``govcsim`` を使用した vcsim の Go 実装も参照します。これは、古い実装との混乱を回避するためのものです。

en: Guidelines for VMware REST module development
ja: VMware REST モジュール開発のガイドライン

en: The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community.
ja: Ansible VMware REST コレクション (`Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_ ではソースコード `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) は、Red Hat とコミュニティーにより維持されます。

en: Contribution process
ja: 貢献プロセス

en: The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`.
ja: vmware_rest コレクションのモジュールは、`vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>` と呼ばれる別のツールにより自動生成されます。

en: If you would like to contribute a change, we would appreciate if you:
ja: 変更に貢献する場合は、以下を行います。

en: submit a Github Pull Request (PR) against the vmware_rest_code_generator project
ja: vmware_rest_code_generator プロジェクトに対して Github Pull Request (PR) を送信します。

en: but also ensure the generated modules are compliant with our quality criteria.
ja: ただし、生成されたモジュールが品質基準に準拠していることを確認します。

en: You will need:
ja: 以下が必要になります。

en: Python 3.6 or greater
ja: Python 3.6 以降

en: the `tox <https://tox.readthedocs.io/en/latest/install.html>` command
ja: `tox <https://tox.readthedocs.io/en/latest/install.html>` コマンド

en: Your contribution should follow the coding style of `Black <https://github.com/psf/black>`. To run the code formatter, just run:
ja: 貢献は、`Black <https://github.com/psf/black>` のコーディングスタイルに従う必要があります。コードフォーマッターを実行するには、以下を実行します。

en: To regenerate the vmware_rest collection, you can use the following commands:
ja: vmware_rest コレクションを再生成するには、以下のコマンドを使用できます。

en: If you also want to update the EXAMPLE section of the modules, run:
ja: モジュールの EXAMPLE セクションも更新する場合は、以下を実行します。

en: Testing with ansible-test
ja: ansible-test を使用したテスト

en: All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`.
ja: すべてのモジュールは、機能テストで対応しています。テストは、:file:`tests/integration/targets/` に置かれます。

en: To run the tests, you will need a vcenter instance and an ESXi.
ja: テストを実行するには、vcenter インスタンスと ESXi が必要です。

en: black code formatter
ja: ブラックコードフォーマッター

en: We follow the coding style of `Black <https://github.com/psf/black>`. You can run the code formatter with the following command.
ja: `Black <https://github.com/psf/black>` のコーディングスタイルに準拠しています。以下のコマンドでコードフォーマッターを実行できます。

en: sanity tests
ja: 健全性テスト

en: Here we use Python 3.8, the minimal version is 3.6.
ja: ここでは Python 3.8 を使用します。最小バージョンは 3.6 です。

en: integration tests
ja: 統合テスト

en: These tests should be run against your test environment.
ja: これらのテストは、テスト環境に対して実行する必要があります。

en: ..warning:: The test suite will delete all the existing DC from your test environment.
ja: ..警告:: テストスイートは、テスト環境から既存の DC をすべて削除します。

en: First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in this example:
ja: まず設定ファイルを準備し、この例では :file:`/tmp/inventory-vmware_rest` とします。

en: To run the tests, use the following command. You may want to adjust the Python version.
ja: テストを実行するには、以下のコマンドを使用して Python バージョンを調整できます。

en: Basic rules
ja: 基本ルール

en: Use standard American English
ja: 標準的なアメリカ英語を使用する

en: Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, and so on).
ja: Ansible は標準的なアメリカ英語を使用します。アメリカ英語では綴りが異なる一般的な単語に注意してください (color と colour、organize と organise など)。

en: Write for a global audience
ja: 世界中の読者に向けて書く

en: Everything you say should be understandable by people of different backgrounds and cultures. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor.
ja: 記載する内容は、生い立ちや文化が違っても理解できるものでなければなりません。イディオムや地域主義は使用せず、誤って解釈されない中立的な表現を使用します。ユーモアな表現は使用しないでください。

en: Follow naming conventions
ja: 命名規則に従う

en: Always follow naming conventions and trademarks.
ja: 命名規則と商標には常に従ってください。

en: Use clear sentence structure
ja: 明確な文構造を使用する

en: Clear sentence structure means:
ja: 明確な文法構造とは、以下のようになります。

en: Start with the important information first.
ja: 重要な情報を最初に示します。

en: Avoid padding/adding extra words that make the sentence harder to understand.
ja: 文章の理解が難しくなるような単語は使用しないでください。

en: Keep it short - Longer sentences are harder to understand.
ja: 文章は短くします。文章が長くなればなるほど、理解が難しくなります。

en: Some examples of improving sentences:
ja: たとえば、以下のように改善できます。

en: Bad:
ja: 問題がある文章:

en: The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.
ja: The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety. (崖の端近くを歩き回ると、下に落ちる危険があります。安全を維持するために安全な距離を保つことをお勧めします。)

en: Better:
ja: 改善例:

en: Danger! Stay away from the cliff.
ja: Danger! Stay away from the cliff. (危険です。崖から離れてください。)

en: Furthermore, large volumes of water are also required for the process of extraction.
ja: Furthermore, large volumes of water are also required for the process of extraction. (また、抜歯のプロセスには、水が大量に必要になります。)

en: Extraction also requires large volumes of water.
ja: Extraction also requires large volumes of water. (抜歯には、大量の水が必要です。)

en: Avoid verbosity
ja: 冗長を避ける

en: Write short, succinct sentences. Avoid terms like:
ja: 短く簡潔な文章を書きます。以下のような用語は使用しないでください。

en: "...as has been said before,"
ja: 「...as has been said before」

en: "..each and every,"
ja: 「...each and every」

en: "...point in time,"
ja: 「...point in time」

en: "...in order to,"
ja: 「...in order to」

en: Highlight menu items and commands
ja: メニュー項目およびコマンドを強調表示する

en: When documenting menus or commands, it helps to **bold** what is important.
ja: メニューまたはコマンドを文書化する場合は、重要な内容を **太字** にすると役立ちます。

en: For menu procedures, bold the menu names, button names, and so on to help the user find them on the GUI:
ja: メニュー手順では、メニュー名、ボタン名などを太字にして、GUI でその文字を見つけられるようにします。

en: On the **File** menu, click **Open**.
ja: **ファイル** メニューで、**開く** をクリックします。

en: Type a name in the **User Name** field.
ja: **ユーザー名** フィールドに名前を入力します。

en: In the **Open** dialog box, click **Save**.
ja: **開く** ダイアログボックスで、**保存** をクリックします。

en: On the toolbar, click the **Open File** icon.
ja: ツールバーで、**ファイルを開く** アイコンをクリックします。

en: For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_::
ja: code または command スニペットの場合は、RST の `code-block ディレクティブ <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_ を使用します。

en: Grammar and Punctuation
ja: 文法および句読点

en: Common Styles and Usage, and Common Mistakes
ja: 一般的なスタイルおよび使用方法、ならびに一般的な間違い

en: Write "Ansible." Not "Ansible, Inc." or "AnsibleWorks The only exceptions to this rule are when we're writing legal or financial statements.
ja: 「Ansible, Inc.」または「AnsibleWorks」とせず、「Ansible」と記述してください。このルールの唯一の例外は、法的文書または財務諸表を作成する場合です。

en: Never use the logotype by itself in body text. Always keep the same font you are using the rest of the sentence.
ja: ロゴマークは、本文で使用しないでください。その他の文章で使用しているフォントを常に使用します。

en: A company is singular in the US. In other words, Ansible is an "it," not a "they."
ja: 米国では、会社は単数形で使用します。つまり、Ansible は、「they」ではなく「it」になります。

en: Capitalization
ja: 大文字

en: If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines.
ja: Ansible の実際の製品、サービス、または部門ではない場合は、大文字にしないでください。見出しの最初の単語の最初の文字だけを大文字にします。

en: Colon
ja: コロン

en: A colon is generally used before a list or series: - The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
ja: 通常、コロンは、リストまたは一連の要素の前に使用されます。- The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.

en: But not if the list is a complement or object of an element in the sentence: - Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail.
ja: ただし、リストが、文内の要素の補語または目的語の場合は、以下のようにします。Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail.

en: Use a colon after "as follows" and "the following" if the related list comes immediately after: wedge The steps for changing directories are as follows:
ja: 直後に関連するリストを追加する場合は、「as follows」および「the following」(次のとおり) の後にコロンを使用します。The steps for changing directories are as follows:

en: Use a colon to introduce a bullet list (or dash, or icon/symbol of your choice):
ja: コロンを使用して、箇条書きリスト (ダッシュ、アイコンまたは記号を使用) を追加します。

en: Commas
ja: コンマ

en: Use serial commas, the comma before the "and" in a series of three or more items:
ja: 3 つ以上の項目が続く場合は、「and」の前にコンマを使用します。

en: "Item 1, item 2, and item 3."
ja: Item 1, item 2, and item 3.

en: It's easier to read that way and helps avoid confusion. The primary exception to this you will see is in PR, where it is traditional not to use serial commas because it is often the style of journalists.
ja: これにより読みやすくなり、混乱を避けることができます。これに対する主な例外は PR です。PR では、多くの場合ジャーナリスト向けのスタイルにより、このようなコンマは使用しません。

en: Commas are always important, considering the vast difference in meanings of the following two statements.
ja: 次の 2 つの文章の意味が大きく異なることを考えると、コンマは常に重要です。

en: Correct punctuation could save Grandma's life.
ja: 正しい句読点により、おばあさんの命を救うことができます。

en: If that does not convince you, maybe this will:
ja: もしくは、以下の例をご覧ください。

en: Contractions
ja: 縮約

en: Do not use contractions in Ansible documents.
ja: Ansible ドキュメントでは、縮約は使用しないでください。

en: Em dashes
ja: エムダッシュ (－)

en: When possible, use em-dashes with no space on either side. When full em-dashes aren't available, use double-dashes with no spaces on either side--like this.
ja: 可能な場合は、両側にスペースを入れずにエムダッシュ (－) を使用します。エムダッシュ (－) が利用できない場合は、両側に空白を入れずに二重ダッシュを使用します。

en: A pair of em dashes can be used in place of commas to enhance readability. Note, however, that dashes are always more emphatic than commas.
ja: 読みやすくするために、コンマの代わりにエムダッシュをペアにして使用できます。ただし、ダッシュはコンマよりも常に強調されることに注意してください。

en: A pair of em dashes can replace a pair of parentheses. Dashes are considered less formal than parentheses; they are also more intrusive. If you want to draw attention to the parenthetical content, use dashes. If you want to include the parenthetical content more subtly, use parentheses.
ja: エムダッシュのペアは、括弧のペアの代わりに使用することもできます。ダッシュは括弧よりも形式的ではないと見なされ、押しつけがましく感じることもあります。括弧内のコンテンツに注意を引きたい場合は、ダッシュを使用します。括弧内のコンテンツにあまり注意を引きたくない場合は、括弧を使用します。

en: When dashes are used in place of parentheses, surrounding punctuation should be omitted. Compare the following examples.
ja: 括弧の代わりにダッシュを使用する場合は、前後の句読点を省略してください。次の例を比較してください。

en: When used in place of parentheses at the end of a sentence, only a single dash is used.
ja: 文末に括弧の代わりに使用する場合は、ダッシュを 1 つだけ使用します。

en: Exclamation points (!)
ja: 感嘆符 (!)

en: Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
ja: 文末には使用しないでください。感嘆符は、bang (!) などのコマンドを参照する場合に使用できます。

en: Gender References
ja: 性別の参照

en: Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers."
ja: ドキュメンテーションでは、性別固有の代名詞は使用しないでください。「he/she」や「his/hers」ではなく「they」および「their」を使用する方が適切です。

en: It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations.
ja: 指示を示す場合は「you」と使用し、より一般的な説明では「the user」、「new users」などを使用すると良いでしょう。

en: Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal.
ja: テクニカルドキュメントを作成する際は、「you」 の意味で「one」を使用しないでください。「one」を使用すると堅苦しくなります。

en: Never use "we" when writing. "We" aren't doing anything on the user side. Ansible's products are doing the work as requested by the user.
ja: 書き込み時に「we」は使用しないでください。「we」は、ユーザー側では何も実行しません。Ansible の製品は、ユーザーの要求に応じて作業を行います。

en: Hyphen
ja: ハイフン

en: The hyphen's primary function is the formation of certain compound terms. Do not use a hyphen unless it serves a purpose. If a compound adjective cannot be misread or, as with many psychological terms, its meaning is established, a hyphen is not necessary.
ja: このハイフンの主な機能は、特定の複合用語の特徴です。目的が満たされない限り、ハイフンは使用しないでください。複合形容詞が間違って解釈されない場合、または多くの心理学用語と同じ様に、その意味が確立されている場合、ハイフンは必要ありません。

en: Use hyphens to avoid ambiguity or confusion:
ja: ハイフンは、あいまいさや混乱を回避するために使用します。

en: In professionally printed material (particularly books, magazines, and newspapers), the hyphen is used to divide words between the end of one line and the beginning of the next. This allows for an evenly aligned right margin without highly variable (and distracting) word spacing.
ja: 適切な編集が必要な出版物 (特に本、雑誌、新聞) では、単語が行をまたがる場合にハイフンを使用します。これにより、単語の間隔が大きく変わる (そして気が散る) ことなく、右マージンを均等に揃えることができます。

en: Lists
ja: リスト

en: Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on.
ja: 箇条書きの構造を同等かつ一貫性のあるものに保ちます。たとえば、1 つの箇条書きが動詞句である場は、すべての箇条書きが動詞句である必要があります。1 つが完全な文である場合、すべての項目が完全な文である必要があります。

en: Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like: * computer * monitor * keyboard * mouse
ja: 箇条書きでは、それぞれ最初の単語を大文字にします。次のような項目のリストなど、単に項目のリストであることが明らかである場合は除きます (* computer * monitor * keyboard * mouse)。

en: When the bulleted list appears within the context of other copy, (unless it's a straight list like the previous example) add periods, even if the bullets are sentence fragments. Part of the reason behind this is that each bullet is said to complete the original sentence.
ja: 箇条書きが他の文章に含まれる場合は、(上の例のような単純なリストでない限り) 箇条書きが完全な文になっていなくてもピリオドを追加します。これは、各箇条書きが元の文を完了すると言われているためです。

en: In some cases where the bullets are appearing independently, such as in a poster or a homepage promotion, they do not need periods.
ja: 箇条書きがポスターやホームページのプロモーションなどのように独立して示される場合、ピリオドは必要ありません。

en: When giving instructional steps, use numbered lists instead of bulleted lists.
ja: 手順を説明するときは、箇条書きの代わりに番号付きリストを使用してください。

en: Months and States
ja: 月および州

en: Abbreviate months and states according to AP. Months are only abbreviated if they are used in conjunction with a day. Example: "The President visited in January 1999." or "The President visited Jan. 12."
ja: AP に従って、月と州の名前を省略します。月は、日付と組み合わせて使用される場合に限り省略されます。たとえば、「The President visited in January 1999.」または「The President visited Jan. 12.」です。

en: Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
ja: 月: Jan.、Feb.、March、April、May、June、July、Aug.、Sept.、Nov.、Dec.

en: States: Ala., Ariz., Ark., Calif., Colo., Conn., Del., Fla., Ga., Ill., Ind., Kan., Ky., La., Md., Mass., Mich., Minn., Miss., Mo., Mont., Neb., Nev., NH, NJ, NM, NY, NC, ND, Okla., Ore., Pa., RI, SC, SD, Tenn., Vt., Va., Wash., W.Va., Wis., Wyo.
ja: 州: Ala.、Ariz.、Ark.、Calif.、Colo.、Conn.、Del.、Fla.、Ga.、Ill.、Ind.、Kan.、Ky.、La.、Md.、Mass.、Mich.、Minn.、Miss.、Mo.、Mont.、Neb.、Nev.、NH、NJ、NM、NY、NC、ND、Okla.、Ore.、Pa.、RI、SC、SD、Tenn.、Vt.、Va.、Wash.、W.Va.、Wis.、Wyo.

en: Numbers
ja: 数字

en: Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It's also acceptable to use numerals in tables and charts.
ja: 1 から 9 までの数字が使用されます。10 以上の値は数字を使用します。「4 million」または「4 GB」などは例外となります。また、表やチャートでは数値を使用することもできます。

en: Phone Numbers
ja: 電話番号

en: Phone number style: 1 (919) 555-0123 x002 and 1 888-GOTTEXT
ja: 電話番号の形式: 1 (919) 555-0123 x002 および 1 888-GOTTEXT

en: Quotations (Using Quotation Marks and Writing Quotes)
ja: 引用 (引用符の使用と引用の記述)

en: "Place the punctuation inside the quotes," the editor said.
ja: "Place the punctuation inside the quotes," the editor said. (「句読点を引用符の中に入れてください」と編集者は言いました)

en: Except in rare instances, use only "said" or "says" because anything else just gets in the way of the quote itself, and also tends to editorialize.
ja: ほとんどの場合は、「said」または「says」だけを使用してください。それ以外は、引用の邪魔になり、編集される傾向があるためです。

en: Place the name first right after the quote:
ja: 引用の直後に名前を追加します。

en: "I like to write first-person because I like to become the character I'm writing," Wally Lamb said.
ja: "I like to write first-person because I like to become the character I'm writing," Wally Lamb said. (「私は自分が書いているキャラクターになりたいので、一人称を書くのが好きです」と Wally Lamb は言いました)

en: Not:
ja: 以下のようにはしないでください。

en: Semicolon
ja: セミコロン

en: Use a semicolon to separate items in a series if the items contain commas:
ja: 項目にコンマが含まれている場合は、セミコロンを使用して項目を区切ります。

en: Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
ja: Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. (私は毎日、朝食にコーヒー、トースト、およびフルーツを食べます。ランチはサラダを食べ、ディナーには、ピーナッツバターのサンドイッチ、クッキー、アイスクリーム、およびチョコレートケーキを食べます)

en: Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, and so on): - I think; therefore, I am.
ja: 接続詞副詞 (however、therefore、otherwise、namely、for example など) の前にセミコロンを使用します。「I think; therefore, I am.」のようにします。

en: Spacing after sentences
ja: 文の後のスペース

en: Use only a single space after a sentence.
ja: 文の後には、シングルスペースのみを使用してください。

en: Time
ja: 時間

en: Time of day is written as "4 p.m."
ja: 時刻は「4 p.m」とします。

en: Ansible style guide
ja: Ansible スタイルガイド

en: Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines:
ja: Ansible スタイルガイドにようこそ! docs.ansible.com に、明確および簡潔で、一貫性のある有用なドキュメントを作成するために、以下のガイドラインが指定されています。

en: Linguistic guidelines
ja: 言語のガイドライン

en: We want the Ansible documentation to be:
ja: Ansible ドキュメントでは、以下を目標にしています。

en: clear
ja: 明確な

en: direct
ja: 直接的な

en: conversational
ja: 会話的な

en: easy to translate
ja: 解釈が容易な

en: We want reading the docs to feel like having an experienced, friendly colleague explain how Ansible works.
ja: Ansible が提供するドキュメントは、経験豊富で友好的な同僚に Ansible の仕組みを説明してもらっていると感じられるようなものにすることを目標にしています。

en: Stylistic cheat-sheet
ja: 文体の早見表

en: This cheat-sheet illustrates a few rules that help achieve the "Ansible tone":
ja: 以下の早見表は、「Ansibleのトーン」を実現するのに役立つルールを示しています。

en: Rule
ja: **ルール**

en: Good example
ja: 適切な例

en: Bad example
ja: 不適切な例

en: Use active voice
ja: 能動態を使用します。

en: You can run a task by
ja: You can run a task by (以下を使用してタスクを実行できます)

en: A task can be run by
ja: A task can be run by (タスクは、以下のように実行できます)

en: Use the present tense
ja: 現在形の使用

en: This command creates a
ja: This command creates a (このコマンドにより...が作成されます。)

en: This command will create a
ja: This command will create a (このコマンドにより...が作成されます)

en: Address the reader
ja: 読者に話すように書きます。

en: As you expand your inventory
ja: As you expand your inventory (インベントリーを展開します)

en: When the number of managed nodes grows
ja: When the number of managed nodes grows (管理ノードの数が増える場合)

en: Use standard English
ja: 標準英語の使用

en: Return to this page
ja: Return to this page (このページに戻る)

en: Hop back to this page
ja: Hop back to this page (このページに戻る)

en: Use American English
ja: アメリカ英語の使用

en: The color of the output
ja: The color of the output (出力の色)

en: The colour of the output
ja: The colour of the output (出力の色)

en: Header case
ja: ヘッダーの書式

en: Headers should be written in sentence case. For example, this section's title is ``Header case``, not ``Header Case`` or ``HEADER CASE``.
ja: ヘッダーは文で使用される書式で記述する必要があります。たとえば、このセクションのタイトルは、``Header Case`` や ``HEADER CASE`` ではなく、``Header case`` と記述します。

en: Avoid using Latin phrases
ja: ラテン語のフレーズを使用しない

en: Latin words and phrases like ``e.g.`` or ``etc.`` are easily understood by English speakers. They may be harder to understand for others and are also tricky for automated translation.
ja: ``e.g.``、``etc.`` のようなラテン語やフレーズは、英語話者であれば簡単に理解できます。ただし、その他の人にとっては理解が難しい場合もあり、自動翻訳の際にも注意が必要になります。

en: Use the following English terms in place of Latin terms or abbreviations:
ja: したがって、ラテン語の用語または略語の代わりに、英語の用語を使用します。

en: Latin
ja: ラテン語

en: English
ja: 英語

en: i.e
ja: i.e (言い換えると)

en: in other words
ja: in other words (言い換えると)

en: e.g.
ja: e.g. (たとえば)

en: for example
ja: for example (たとえば)

en: etc
ja: etc (など)

en: and so on
ja: and so on (など)

en: via
ja: via (により)

en: by/ through
ja: by/ through (により)

en: vs./versus
ja: vs./versus (対)

en: rather than/against
ja: rather than/against (対)

en: reStructuredText guidelines
ja: reStructuredText のガイドライン

en: The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages:
ja: Ansible ドキュメントは reStructuredText で記述され、Sphinx によって処理されます。すべての rST ページに対して、以下の技術的または機械的なガイドラインが指定されています。

en: Header notation
ja: ヘッダーの表記法

en: `Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ can use a variety of notations. Sphinx will 'learn on the fly' when creating a hierarchy of headers. To make our documents easy to read and to edit, we follow a standard set of header notations. We use:
ja: `Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ は、さまざまな表記を使用できます。Sphinx は、ヘッダーの階層を作成するときに「オンザフライで学習」します。ドキュメントを読みやすく、編集できるようにするために、標準のヘッダー表記法に従います。以下を使用します。

en: ``###`` with overline, for parts:
ja: 上線付き (各部分の場合): ``###``

en: ``***`` with overline, for chapters:
ja: 上線付き (章の場合): ``***``

en: ``===`` for sections:
ja: セクションの場合: ``===``

en: ``---`` for subsections:
ja: サブセクションの場合: ``---``

en: ``^^^`` for sub-subsections:
ja: サブサブセクションの場合: ``^^^``

en: ``"""`` for paragraphs:
ja: パラグラフの場合: ``"""``

en: Syntax highlighting - Pygments
ja: 構文の強調表示 - Pygment

en: The Ansible documentation supports a range of `Pygments lexers <https://pygments.org/>`_ for `syntax highlighting <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples>`_ to make our code examples look good. Each code-block must be correctly indented and surrounded by blank lines.
ja: Ansible ドキュメントは、コード例の見栄えを良くするため、`構文の強調表示 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples>`_ の `Pygments lexers <https://pygments.org/>`_ の範囲をサポートします。コードブロックは適切にインデントされ、空の行で囲む必要があります。

en: The Ansible documentation allows the following values:
ja: Ansible ドキュメントでは、以下の値を使用できます。

en: none (no highlighting)
ja: なし (強調表示なし)

en: ansible-output (a custom lexer for Ansible output)
ja: ansible-output (Ansible 出力用のカスタム lexer)

en: For example, you can highlight Python code using following syntax:
ja: たとえば、以下の構文を使用して Python コードを強調表示できます。

en: Internal navigation
ja: 内部ナビゲーション

en: `Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ work together to help users find related content. Local tables of contents also help users navigate quickly to the information they need. All internal links should use the ``:ref:`` syntax. Every page should have at least one anchor to support internal ``:ref:`` links. Long pages, or pages with multiple levels of headers, can also include a local TOC.
ja: `アンカー (ラベルとも呼ばれます) およびリンク <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>` は、関連コンテンツを見つけやすくするために、あるローカルテーブルも必要な情報に移動するのに役立ちます。すべての内部リンクで ``:ref:`` 構文を使用する必要があります。また、各ページには内部 ``:ref:`` リンクに対応するアンカーが 1 つ以上必要になります。長いページまたは複数のヘッダーレベルを持つページにも、ローカルの TOC を使用できます。

en: Adding anchors
ja: アンカーの追加

en: Include at least one anchor on every page
ja: すべてのページに少なくとも 1 つのアンカーを含める。

en: Place the main anchor above the main header
ja: メインヘッダーの上にメインアンカーを配置する。

en: If the file has a unique title, use that for the main page anchor::
ja: このファイルに一意のタイトルがある場合は、メインページのアンカーに使用します。

en: You may also add anchors elsewhere on the page
ja: ページにアンカーを追加することもできます。

en: Adding internal links
ja: 内部リンクの追加

en: All internal links must use ``:ref:`` syntax. These links both point to the anchor defined above:
ja: すべての内部リンクには ``:ref:`` 構文を使用する必要があります。これらのリンクは共に、上で定義したアンカーを指定します。

en: The second example adds custom text for the link.
ja: 2 つ目の例は、リンクのカスタムテキストを追加します。

en: Adding links to modules and plugins
ja: モジュールおよびプラグインへのリンクの追加

en: Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part of the links:
ja: Ansible 2.10 以降は、リンクの一部として、拡張された完全修飾コレクション名 (FQCN) が必要です。

en: For example:
ja: 例:

en: displays as :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`.
ja: :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>` として表示します。

en: Modules require different suffixes from other plugins:
ja: モジュールには、他のプラグインとは異なるサフィックスが必要です。

en: Module links use this extended FQCN module name with ``_module`` for the anchor.
ja: モジュールリンクでは、この広範な FQCN モジュール名に、アンカーに ``_module`` を使用します。

en: Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for example).
ja: プラグインのリンクは、この広範な FQCN プラグイン名をプラグインタイプ (``_connection`` など) で使用します。

en: ``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy.
ja: ``ansible.builtin`` は、``ansible.base`` に含まれているモジュールの FQCN です。ドキュメントのリンクは、``ansible_collections`` を FQCN の前に付ける唯一の場所です。これは、Ansible Galaxy のコレクションからドキュメントを適切に取得するために、ドキュメントビルドスクリプトにより使用されます。

en: Adding local TOCs
ja: ページ内 (ローカル) 目次の追加

en: The page you're reading includes a `local TOC <https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents>`_. If you include a local TOC:
ja: このページには `ローカル TOC <https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents>`_ が含まれます。ローカルの TOC を追加する場合は、以下のようになります。

en: place it below, not above, the main heading and (optionally) introductory text
ja: 目次の下に、主要な見出しと (任意で) 紹介文を追加します。目次の上には追加しないでください。

en: use the ``:local:`` directive so the page's main header is not included
ja: そのページの主要なヘッダーが含まれないように ``:local:`` ディレクティブを使用します。

en: do not include a title
ja: タイトルは除外します。

en: The syntax is:
ja: 構文は以下のようになります。

en: More resources
ja: 参考資料

en: These pages offer more help with grammatical, stylistic, and technical rules for documentation.
ja: 以下のページでは、ドキュメントに関する文法、スタイル、および技術的なルールを紹介しています。

en: How to contribute to the Ansible documentation
ja: Ansible ドキュメントへの貢献方法

en: How to build the Ansible documentation
ja: Ansible ドキュメントのビルド方法

en: #ansible-docs IRC chat channel
ja: IRC チャットチャンネル (#ansible-docs)

en: Resources
ja: リソース

en: Follow the style of the :ref:`Ansible Documentation<ansible_documentation>`
ja: :ref:`Ansible ドキュメント<ansible_documentation>` のスタイルに従ってください。

en: Ask for advice on IRC, on the ``#ansible-devel`` `libera.chat channel <https://libera.chat/>`_
ja: `libera.chat channel <https://libera.chat/>`_ の IRC ``#ansible-devel`` で質問してください。

en: Review these online style guides:
ja: オンラインで利用できるスタイルガイドを参照してください。

en: Writing documentation so search can find it
ja: 検索用のドキュメントの作成

en: One of the keys to writing good documentation is to make it findable. Readers use a combination of internal site search and external search engines such as Google or duckduckgo.
ja: 優れたドキュメントを作成するための鍵の 1 つは、ドキュメントを見つけやすくすることです。読者は、サイト内検索や、Google、duckduckgo などの外部検索エンジンを組み合わせて使用します。

en: To ensure Ansible documentation is findable, you should:
ja: Ansible ドキュメントが見つかるようにするには、以下を行う必要があります。

en: Use headings that clearly reflect what you are documenting.
ja: ドキュメントの内容を明確に反映させる見出しを使用します。

en: Use numbered lists for procedures or high-level steps where possible.
ja: 可能な場合は、番号付きの一覧または手順の概要手順に使用します。

en: Avoid linking to github blobs where possible.
ja: 可能な限り、github ブログにはリンクしないでください。

en: Using clear headings in documentation
ja: ドキュメントで明確な見出しの使用

en: We all use simple English when we want to find something. For example, the title of this page could have been any one of the following:
ja: 何かを探すときは、簡単な英語を使います。たとえば、このページのタイトルは次のいずれかになります。

en: Search optimization
ja: Search optimization (検索の最適化)

en: Findable documentation
ja: Findable documentation (検索可能なドキュメント)

en: Writing for findability
ja: Writing for findability (見やすくするための記述)

en: What we are really trying to describe is - how do I write documentation so search engines can find my content? That simple phrase is what drove the title of this section. When you are creating your headings for documentation, spend some time to think about what you would type in a search box to find it, or more importantly, how someone less familiar with Ansible would try to find that information. Your heading should be the answer to that question.
ja: ここで説明しようとしているのは、「検索エンジンがコンテンツを見つけられるようにするドキュメントの書き方」です。その単純なフレーズが、このセクションのタイトルになりました。ドキュメントの見出しを作成するときは、検索ボックスに何を入力して検索するのか、さらに重要なことに、Ansible にあまり詳しくないユーザーがその情報をどのように見つけようとするかを考える時間を設けてください。見出しは、その質問に対する答えであるべきです。

en: One word of caution - you do want to limit the size of your headings. A full heading such as `How do I write documentation so search engines can find my content?` is too long. Search engines would truncate anything over 50 - 60 characters. Long headings would also wrap on smaller devices such as a smart phone.
ja: 注記 - 見出しのサイズを制限する場合は、`How do I write documentation so search engines can find my content?` などの見出しにすると長すぎます。検索エンジンは 50 ~ 60 文字を超えるものは切り捨てます。長い見出しも、スマートフォンなどの小規模なデバイスでは折り返されます。

en: Using numbered lists for `zero position` snippets
ja: `zero position` スニペットの番号付きのリストの使用

en: Google can optimize the search results by adding a `feature snippet <https://support.google.com/websearch/answer/9351707>`_ at the top of the search results. This snippet provides a small window into the documentation on that first search result that adds more detail than the rest of the search results, and can occasionally answer the reader's questions right there, or at least verify that the linked page is what the reader is looking for.
ja: Google は、検索結果の上部に `機能スニペット <https://support.google.com/websearch/answer/9351707>`_ を追加して検索結果を最適化できます。このスニペットは、最初の検索結果に関するドキュメントに小さなウィンドウを提供し、残りの検索結果よりも詳細を追加し、時には読者の質問にその場で答えたり、少なくともリンク先のページが読者の探しているものであることを確認することができます。

en: Google returns the feature snippet in the form of numbered steps. Where possible, you should add a numbered list near the top of your documentation page, where appropriate. The steps can be the exact procedure a reader would follow, or could be a high level introduction to the documentation topic, such as the numbered list at the top of this page.
ja: Google は番号付きの手順の機能スニペットを返します。可能であれば、必要に応じて、ドキュメントページの上部付近に番号付きリストを追加する必要があります。手順は、読者が従う正確な手順にすることも、このページの上部にある番号付きリストなど、ドキュメントトピックの概要を説明することもできます。

en: Problems with github blobs on search results
ja: 検索結果に関する github ブロブの問題

en: Search engines do not typically return github blobs in search results, at least not in higher ranked positions. While it is possible and sometimes necessary to link to github blobs from documentation, the better approach would be to copy that information into an .rst page in Ansible documentation.
ja: 検索エンジンは通常、少なくとも上位の位置では、検索結果に github ブロブを返しません。ドキュメントから github ブロブにリンクすることは可能であり、場合によっては必要ですが、より良いアプローチは、その情報を Ansible ドキュメントの .rst ページにコピーすることです。

en: Other search hints
ja: 他の検索ヒント

en: While it may not be possible to adapt your documentation to all search optimizations, keep the following in mind as you write your documentation:
ja: すべての検索最適化にドキュメントを調整することができない場合もありますが、ドキュメントを作成する場合は、以下の点に留意してください。

en: **Search engines don't parse beyond the `#` in an html page.** So for example, all the subheadings on this page are appended to the main page URL. As such, when I search for 'Using number lists for zero position snippets', the search result would be a link to the top of this page, not a link directly to the subheading I searched for. Using :ref:`local TOCs <local_toc>` helps alleviate this problem as the reader can scan for the header at top of the page and click to the section they are looking for. For critical documentation, consider creating a new page that can be a direct search result page.
ja: **検索エンジンは、html ページ内の `#` 以降は解析しません。** そのため、たとえば、このページのすべての小見出しは、メインページの URL に付加されています。そのため、「Using number lists for zero position snippets」と検索すると、検索結果はこのページの冒頭へのリンクになり、検索した小見出しへの直接のリンクにはなりません。:ref:`ローカル TOC <local_toc>` を使用すると、読者がページに上部のヘッダーに目を通して、探しているセクションをクリックできるため、この問題を軽減することができます。重要な文書については、検索結果のページに直接アクセスできるように新しいページを作成することを検討してください。

en: **Make your first few sentences clearly describe your page topic.** Search engines return not just the URL, but a short description of the information at the URL. For Ansible documentation, we do not have description metadata embedded on each page. Instead, the search engines return the first couple of sentences (140 characters) on the page. That makes your first sentence or two very important to the reader who is searching for something in Ansible.
ja: **最初の 2、3 文でページのトピックを明確に説明してください。** 検索エンジンは URL だけでなく、その URL にある情報の簡単な説明も返します。Ansible ドキュメントの場合は、各ページに説明メタデータが埋め込まれていません。その代わり、検索エンジンはページの最初の 2、3 文 (140 文字) を返します。そのため、Ansibleで何かを検索している読者にとって、最初の 1〜2 文が非常に重要になります。

en: Spelling - Word Usage - Common Words and Phrases to Use and Avoid
ja: スペル、単語の使用、および使用または回避する一般的な単語とフレーズ

en: Acronyms
ja: 略語

en: Always uppercase. An acronym is a word formed from the initial letters of a name, such as ROM for Read-only memory, SaaS for Software as a Service, or by combining initial letters or part of a series of words, such as LILO for LInux LOader.
ja: 常に大文字です。頭字語とは、ROM (Read-Only Memory) や SaaS (Software as a Service) のように名前の頭文字から形成された単語や、LILO (LInux LOader) のように一連の単語の頭文字や一部を組み合わせて形成された単語のことです。

en: Spell out the acronym before using it in alone text, such as "The Embedded DevKit (EDK)..."
ja: 略語は、単独で使用する前に、「The Embedded devkit (EDK)...」のように文字を略さずに書いて使用します。

en: Applications
ja: アプリケーション

en: When used as a proper name, use the capitalization of the product, such as GNUPro or Source-Navigator. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
ja: 固有名詞として使用する場合は、GNUPro または Source-Navigator のように製品の大文字を使用します。コマンドとして使用する場合は、「To start GCC, type ``gcc``.」(GCC を起動する場合は、``gcc`` を入力します) のように、適切な小文字を使用します。

en: "vi" is always lowercase.
ja: 「vi」は常に小文字です。

en: This is often used to mean "because", but has other connotations, for example, parallel or simultaneous actions. If you mean "because", say "because".
ja: 原因を示す場合によく使用されますが、並列または同時の操作など、他の意味もあります。「原因」を意味する場合は、「because」を使用してください。

en: Use "requests" instead.
ja: 代わりに「requests」を使用してください。

en: Assure implies a sort of mental comfort. As in "I assured my husband that I would eventually bring home beer."
ja: 「assure」は、一種の精神的な安心さを意味します。たとえば、「I assured my husband that I would eventually bring home beer. (私は夫に最終的に家のビールを持ってくることを約束しました)」のように使用します。

en: Ensure means "to make sure."
ja: 「ensure」は、「確実に」を意味します。

en: Insure relates to monetary insurance.
ja: 「insure」は、金銭的な保険に関係があります。

en: This is a verb. You "back up" files; you do not "backup" files.
ja: これは動詞です。ファイルを「バックアップ」するときは、「backup」ではなく、「back up」と記載します (You back up files)。

en: This is a noun. You create "backup" files; you do not create "back up" files.
ja: これは名詞です。「バックアップ」ファイルを作成するときは、「back up」ではなく、「backup」と記載します (You create backup files)。

en: Correct. Avoid using backwards unless you are stating that something has "backwards compatibility."
ja: 適切です。「backwards compatibility」(後方互換性) 以外の説明に、「backward」という単語を使用しないでください。

en: Correct as is.
ja: そのまま使用します。

en: Use "using" instead.
ja: 代わりに「using」を使用してください。

en: Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it's less tentative.
ja: 「can」は、可能な操作や条件を説明するのに使用します。許可が必要な状況を説明するには、「may」を使用します。「can」、「could」、または「may」のいずれかが当てはまる場合は、「can」を使用します (暫定的な意味合いが少ないため)。

en: CD or cd
ja: CD または cd

en: When referring to a compact disk, use CD, such as "Insert the CD into the CD-ROM drive." When referring to the change directory command, use cd.
ja: コンパクトディスクを参照する場合は、CD を使用します。たとえば、「Insert the CD into the CD-ROM drive.」(CD を CD-ROM ドライブに挿入します。) とします。ディレクトリーを変更する change directory コマンドを示す場合は、cd を使用します。

en: Correct. Do not use "cdrom," "CD-Rom," "CDROM," "cd-rom" or any other variation. When referring to the drive, use CD-ROM drive, such as "Insert the CD into the CD-ROM drive." The plural is "CD-ROMs."
ja: 「cdrom」、「CD-Rom」、「CDROM」、「cd-rom」などの表記は使用しないでください。ドライブを参照する場合は、「Insert the CD into the CD-ROM drive (CD-ROM ドライブなど)」のように「CD-ROM drive」を使用します。複数形は「CD-ROMs」となります。

en: Correct. Do not use "command-line" or "commandline" as a noun. If used as an adjective, "command-line" is appropriate, for example "command-line arguments".
ja: 適切です。「command-line」または「commandline」を名詞として使用しないでください。形容詞として使用する場合は、「command-line arguments」のように、「command-line」が適切です。

en: Use "command line" to describes where to place options for a command, but not where to type the command. Use "shell prompt" instead to describe where to type commands. The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt.
ja: 「コマンドライン」を使用して、コマンドのオプションを追加する場所を記述しますが、コマンドを入力する場所は記述しません。コマンドを入力する場所を説明する場合は、代わりに「shell prompt」を使用します。コマンドが期待される画面上の行となります。通常、コマンドラインは、最後に表示されるコマンドプロンプトを含む行となります。

en: Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled "Daylight Savings", with an "s" at the end. Other common variations are "Summer Time"and "Daylight-Saving Time". (https://www.timeanddate.com/time/dst/daylight-savings-time.html)
ja: 適切です。「daylight savings time」は使用しないでください。「Daylight Saving Time (DST)」は、「Daylight Savings」のように、最後に s が付いている場合がありますが、これは間違いです。その他の一般的な表記法には、「Summer Time」および「Daylight-Saving Time」があります (https://www.timeanddate.com/time/dst/daylight-savings-time.html))。

en: Correct. Do not use "down load" or "down-load."
ja: 適切です。「down load」または「down-load」は使用しないでください。

en: Spell it out: "For example."
ja: 省略せずに「For example」とします。

en: When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system.
ja: 名詞として使用される場合、フェイルオーバーとは、プライマリーシステムに障害が発生したり、サービスのために一時的に停止した場合に、自動的にスタンバイデータベース、サーバー、またはネットワークに切り替えるバックアップ操作のことです。フェイルオーバーは、常にアクセス可能であることが求められるミッションクリティカルなシステムの重要なフォールトトレランス機能となります。フェイルオーバーは、自動的かつユーザーに透過的に、障害や停止したシステムからのリクエストを、プライマリーシステムの操作を模倣したバックアップシステムにリダイレクトします。

en: When used as a verb, fail over is two words since there can be different tenses such as failed over.
ja: 動詞として使用する場合は、時制を変えられるように (failed over など)、2 つの単語にします。

en: Fewer is used with plural nouns. Think things you could count.  Time, money, distance, and weight are often listed as exceptions to the traditional "can you count it" rule, often thought of a singular amounts (the work will take less than 5 hours, for example).
ja: fewer は、複数形の名詞で使用します。数を数えることができるものに使用します。時間、お金、距離、および重量は、従来の「数えることができるか」ルールの例外として挙げられることが多く、通常は 1 つの量と見なされます。たとえば、「the work will take less than 5 hours」(作業にかかる時間は 5 時間未満です)。

en: Correct. Do not use "filename."
ja: 適切です。「filename」は使用しないでください。

en: Correct. Do not use "filesystem." The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure. Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection.
ja: 適切です。「filesystem」は使用しないでください。オペレーティングシステムまたはプログラムがファイルを整理し、追跡するために使用するシステムです。たとえば、階層ファイルシステムは、ディレクトリーを使用してファイルをツリー構造に編成するものです。オペレーティングシステムは独自のファイル管理システムを提供していますが、別のファイル管理システムを使用することもできます。このようなシステムはオペレーティングシステムとスムーズに対話しますが、バックアップ手順の改善やファイル保護の強化など、より多くの機能を提供します。

en: For example," instead.
ja: 代わりに「For example」を使用します。

en: Use "For more information"
ja: 「For more information」を使用します。

en: Use "therefore".
ja: 「therefore」を使用します。

en: Correct. Avoid using "forwards."
ja: 適切です。「forwards」は使用しないでください。

en: 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Gigabyte is often abbreviated as G or GB.
ja: 2 の 30乗 (1,073,741,824) バイト。1 ギガバイトは 1,024 メガバイトに相当します。ギガバイトは、G または GB と略されることがよくあります。

en: Avoid. Use "must" instead.
ja: 使用しないようにしてください。代わりに "must" を使用してください。

en: Correct. Do not use "high availability."
ja: 適切です。「hight availability」は使用しないでください。

en: Correct. Do not use highly-available."
ja: 適切です。高可用性は使用しないでください。

en: Correct. Do not use host name.
ja: 適切です。ホスト名は使用しないでください。

en: Spell it out: "That is."
ja: 「That is」を使用してください。

en: Avoid. Use "installation program" instead.
ja: 使用しないでください。代わりに「installation program」を使用してください。

en: It's and its
ja: It's および its

en: "It's" is a contraction for "it is;" use "it is" instead of "it's." Use "its" as a possessive pronoun (for example, "the store is known for its low prices").
ja: 「It's」は「it is」の短縮形です。「it's」ではなく「it is」を使用します。所有代名詞は「its」と使用します。たとえば「the store is known for its low prices」(この店は低価格で知られています) となります。

en: Less is used with singular nouns. For example "View less details" wouldn't be correct but "View less detail" works. Use fewer when you have plural nouns (things you can count).
ja: Less は単数名詞で使用されます。たとえば、「View less details」は間違っていますが、「View less detail」は適切です。複数名詞 (数えられる物) には、「fewer」を使用します。

en: Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." Linux is a registered trademark of Linus Torvalds.
ja: 適切です。コマンドを参照している場合 (たとえば「To start Linux, type linux」(Linux を起動する場合は、linux と入力します)) を除き、「LINUX」または「linux」を使用しないでください。Linux は、Linus Torvalds の登録商標です。

en: A noun used to refer to the login prompt, such as "At the login prompt, enter your username."
ja: ログインプロンプトを示すために使用している名詞です。たとえば、「At the login prompt, enter your username.」(ログインプロンプトでユーザー名を入力してください。) とします。

en: A verb used to refer to the act of logging in. Do not use "login," "loggin," "logon," and other variants. For example, "When starting your computer, you are requested to log in..."
ja: ログインの動作を参照するために使用される動詞です。「login」、「loggin」、「loggin」などの形は使用しないでください。たとえば、「When starting your computer, you are requested to log in...」(コンピューターを起動すると、ログインを要求されます...) と表示されます。

en: To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure -- you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs.
ja: コンピューターセッションを開始できるように、コンピューターシステムまたはネットワークにユーザーを認識させることです。ほとんどのコンピューターにはログオン手順がありません。マシンの電源を入れれば動くためです。ただし、大規模システムやネットワークの場合には、通常、コンピュータシステムでプログラムを実行する前に、ユーザー名とパスワードを入力する必要があります。

en: Use "Several" or something equivalent instead.
ja: 代わりに「several」などの単語を使用してください。

en: This means "be careful to remember, attend to, or find out something." For example, "...make sure that the rhedk group is listed in the output." Try to use verify or ensure instead.
ja: これは、「何かを覚えたり、注意したり、見つけたりするように注意する」という意味です。たとえば、「...make sure that the rhedk group is listed in the output.」(rhedk グループが出力の一覧に含まれていることを確認してください) となります。代わりに verify や ensure を使用してください。

en: Correct. Two words. Do not use "manpage"
ja: 適切です。2 つの単語になります。「manpage」は使用しないでください。

en: When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context).
ja: MB は、メガバイト (状況に応じて 1,000,000 バイトまたは 1,048,576 バイト) の略語です。

en: When spelled Mb, short for megabit.
ja: Mb は、メガビットの略語です。

en: Short for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps.
ja: 1 秒あたりのメガバイトの略語で、データ転送速度の測定単位です。通常、大容量ストレージデバイスは、MBps で表されます。

en: Common open source database server and client package. Do not use "MYSQL" or "mySQL."
ja: 一般的なオープンソースデータベースサーバーおよびクライアントパッケージです。「MYSQL」または「mySQL」は使用しないでください。

en: Correct. Use when referring to the access permissions of files or directories.
ja: 適切です。ファイルまたはディレクトリーのアクセスパーミッションを参照する場合に使用します。

en: Depends. If used as a noun, it is the actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." If used as an adjective, "real-time" is appropriate. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor."
ja: 状況によって異なります。名詞として使用する場合は、それは何かが行われる実際の時間になります。たとえば、「The computer may partly analyze the data in real time (as it comes in) -- R. H. March」(コンピューターはデータをリアルタイムで部分的に分析する場合があります。(R. H.マーチ)) となります。形容詞として使用する場合は、「real-time」が適切です。たとえば、「XEmacs is a self-documenting, customizable, extensible, real-time display editor.」(XEmacs は、自己文書化を行う、カスタマイズ可能で、拡張可能な、リアルタイムディスプレイエディターです) となります。

en: Use to indicate a reference (within a manual or website) or a cross-reference (to another manual or documentation source).
ja: 参照 (マニュアルまたは Web サイト内) または相互参照 (別のマニュアルまたはドキュメントソース) を示すために使用します。

en: Don't use. Use "Refer to" instead.
ja: 使用しないでください。代わりに「Refer to」を使用してください。

en: This is often used to mean "because", but "since" has connotations of time, so be careful. If you mean "because", say "because".
ja: この単語は「原因」を意味するためによく使用されますが、「since」には時間の意味合いがあるため、注意してください。「原因」を意味する場合は、「because」を使用してください。

en: Use "Instructs" instead.
ja: 代わりに「instructs」を使用してください。

en: "That" introduces a restrictive clause-a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it. "Which" introduces a non-restrictive, parenthetical clause-a clause that could be omitted without affecting the meaning of the sentence. For example: The car was travelling at a speed that would endanger lives. The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk. Use "who" or "whom," rather than "that" or "which," when referring to a person.
ja: 「That」は、制限的関係詞節を導入します。これは、文が意味をなすために必要な節です。制限的関係詞節は、多くの場合、その前にある名詞または句を定義します。「Which」は、非制限の、括弧で囲まれた節を導入します。つまり、文の意味に影響を与えずに省略することができる節です。たとえば、「The car was travelling at a speed that would endanger lives.」(人命を危険にさらす速度で車が走行していました。) と、「The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk.」(人命を危険にさらす速度で走行していた車が歩道にのり上げました) です。人を指す場合は、「that」または「which」ではなく「who」または「whom」を使用します。

en: "Then" refers to a time in the past or the next step in a sequence. "Than" is used for comparisons.
ja: 「then」は、ひと続きのものの中から、シーケンスの過去のステップまたは次のステップの時間を指します。比較には「than」が使用されます。

en: Correct. Do not use "third party".
ja: 適切です。「third party」は使用しないでください。

en: Correct. Do not use "trouble shoot" or "trouble-shoot." To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used.
ja: 適切です。「trouble shoot」または「trouble-shoot」は使用しないでください。問題の原因を特定して修正するためのものです。コンピューターシステムの場合は、通常、問題がハードウェアに関連するものと考えられる場合に使用されます。問題がソフトウェアにあることが分かっている場合に、より一般的に使用されるのは「debug」です。

en: Correct as is, no periods.
ja: このとおりに使用します。ピリオドは付けません。

en: Correct. Do not use "Unix" or "unix." UNIX® is a registered trademark of The Open Group.
ja: 適切です。「Unix」または「unix」は使用しないでください。UNIX® は、The Open Group の登録商標です。

en: Don't use. Use Clear.
ja: 使用しないでください。「Clear」を使用します。

en: When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may wish to access your database."
ja: 読み手を示す場合は、「user」ではなく「you」を使用します。たとえば、「The user must...」は正しくありません。代わりに「You must...」を使用してください。複数のユーザーを示す場合は、「users」を使用できます。たとえば、「Other users may to access your database.」(その他のユーザーがデータベースにアクセスすることを望む可能性があります) です。

en: Correct. Do not use "user name."
ja: 適切です。「user name」は使用しないでください。

en: When using as a reference ("View the documentation available online."), do not use View. Use "Refer to" instead.
ja: 参照として使用する場合、たとえば「View the documentation available online.」(オンラインで使用可能なドキュメントを参照してください) とする場合は、「view」を使用しないでください。代わりに「refer to」を使用してください。

en: Don't use to refer to a file that exists in a directory. Use "In".
ja: ディレクトリーにあるファイルを参照する場合は使用しないでください。「In」を使用してください。

en: Correct. Capitalize each word. Abbreviate as "WWW" or "Web."
ja: 適切です。各単語を大文字にします。省略形は「WWW」または「Web」を使用します。

en: Correct. Do not use "web page" or "Web page."
ja: 適切です。「web page」または「Web page」は使用しないでください。

en: Correct. Do not use "webserver". For example, "The Apache HTTP Server is the default Web server..."
ja: 適切です。「webserver」は使用しないでください。たとえば、「The Apache HTTP Server is the default Web server...」(Apache HTTP サーバーはデフォルトの Web サーバー...) です。

en: Correct. Do not use "web site" or "Web site." For example, "The Ansible website contains ..."
ja: 適切です。「web site」または「Web site」は使用しないでください。たとえば、「The Ansible website contains ...」(Ansible web サイトに...含まれます) となります。

en: Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. For example: Who owns this? To whom does this belong?
ja: 主語には、代名詞「who」を使用します。直接目的語、間接目的語、または前置詞の目的語には、代名詞の目的格「whom」を使用します。たとえば、「Who owns this?」(これは誰が所有していますか?) や、「To whom does this belong?」(これは誰のものですか?) となります。

en: Do not use future tense unless it is absolutely necessary. For instance, do not use the sentence, "The next section will describe the process in more detail." Instead, use the sentence, "The next section describes the process in more detail."
ja: 絶対に必要な場合を除いて、未来時制は使用しないでください。たとえば、「The next section will describe the process in more detail.」(次のセクションでプロセスを詳しく説明します) ではなく、「The next section describes the process in more detail.」とします。

en: Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they may not "need" something but may still "want" something).
ja: 「desire」および「wish」の代わりに「need」を使用します。読者の操作が任意の場合 (つまり、何かを「必要」とはしないかもしれないけど、それでも何かを「望んでいる」可能性がある場合) は「want」を使用します。

en: Correct. Do not capitalize the "x."
ja: 適切です。「x」は大文字にしないでください。

en: Do not use. Do not use "Hammer". Always use "AMD64 and Intel® EM64T" when referring to this architecture.
ja: 「Hammer」を使用しないでください。このアーキテクチャーを参照する場合は必ず「AMD64 and Intel® EM64T」としてください。

en: Correct. Do not use "I," "he," or "she."
ja: 適切です。「I」、「he」、「she」は使用しないでください。

en: Try to avoid using this. For example, "you may" can be eliminated from this sentence "You may double-click on the desktop..."
ja: この表現は使用しないようにしてください。たとえば、「You may double-click on the desktop...」(あなたはデスクトップ上でダブルクリックすることができます...) という意味の文からは「you may」を省くことができます。

en: Trademark Usage
ja: 商標の使用方法

en: Why is it important to use the TM, SM, and ® for our registered marks?
ja: 登録商標に TM、SM、および ® を使用することが重要な理由

en: Before a trademark is registered with the United States Patent and Trademark Office it is appropriate to use the TM or SM symbol depending whether the product is for goods or services. It is important to use the TM or SM as it is notification to the public that Ansible claims rights to the mark even though it has not yet been registered.
ja: 商標が米国特許商標局に登録される前に、TM または SM のどちらの記号を使用するのが適切かは、製品が商品用かサービス用かによって異なります。Ansible がそのマークに対する権利を主張していることを公に通知するために、商標が登録される前から TM または SM を使用することが重要です。

en: Once the trademark is registered, it is appropriate to use the symbol in place of the TM or SM. The symbol designation must be used in conjunction with the trademark if Ansible is to fully protect its rights. If we don't protect these marks, we run the risk of losing them in the way of Aspirin or Trampoline or Escalator.
ja: 商標が登録されたら、TM または SM の代わりにシンボルを使用することが適切です。Ansible がその権利を完全に保護する場合は、シンボルと商標を組み合わせて使用する必要があります。これらのマークを保護しないと、アスピリン、トランポリン、エスカレーターなどのように、権利を失う場合があります。

en: General Rules:
ja: 一般的なルール:

en: Trademarks should be used on 1st references on a page or within a section.
ja: 商標は、ページ内またはセクション内で最初に参照する際に使用する必要があります。

en: Use Red Hat® Ansible® Automation Platform or Ansible®, on first reference when referring to products.
ja: 製品を示す最初の参照では、Red Hat® Ansible® Automation Platform or Ansible® または Ansible® を使用します。

en: Use "Ansible" alone as the company name, as in "Ansible announced quarterly results," which is not marked.
ja: 「Ansible」を会社名として使用する場合は、「Ansible announced quarterly results」(Ansible 四半期決算発表) のように、マークを付けずに使用します。

en: Also add the trademark disclaimer. * When using Ansible trademarks in the body of written text, you should use the following credit line in a prominent place, usually a footnote.
ja: 商標の免責事項も追加します。* 文章の本文に Ansible 商標を使用する場合は、目立つ場所、通常は脚注に次のような行を追加する必要があります。

en: For Registered Trademarks: - [Name of Trademark] is a registered trademark of Red Hat, Inc. in the United States and other countries.
ja: 登録商標の場合 - [Name of Trademark] is a registered trademark of Red Hat, Inc. in the United States and other countries.

en: For Unregistered Trademarks (TMs/SMs): - [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
ja: 非登録商標の場合 (TM/SM): - [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.

en: For registered and unregistered trademarks: - [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
ja: 登録商標および未登録商標の場合: [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.

en: Guidelines for the proper use of trademarks:
ja: 商標を適切な使用するためのガイドライン:

en: Always distinguish trademarks from surround text with at least initial capital letters or in all capital letters.
ja: 商標を、周囲のテキストと区別するために、少なくとも頭文字を大文字にするか、すべての文字を大文字にします。

en: Always use proper trademark form and spelling.
ja: 常に適切な商標の形式とスペルを使用してください。

en: Never use a trademark as a noun. Always use a trademark as an adjective modifying the noun.
ja: 商標は、動詞として使用しないでください。商標は、常に名詞を修飾する形容詞として使用してください。

en: Correct: Red Hat® Ansible® Automation Platform system performance is incredible.
ja: 正しい使用方法: 「Red Hat® Ansible® Automation Platform system performance is incredible. (Red Hat® Ansible® Automation Platform システムのパフォーマンスは驚異的です)」

en: Incorrect: Ansible's performance is incredible.
ja: 誤った使用方法: 「Ansible's performance is incredible. (Ansible のパフォーマンスは脅威的です)」

en: Never use a trademark as a verb. Trademarks are products or services, never actions.
ja: 商標は、動詞として使用しないでください。商標は製品またはサービスであり、動作ではありません。

en: Correct: "Orchestrate your entire network using Red Hat® Ansible® Automation Platform."
ja: 正しい使用方法: 「Orchestrate your entire network using Red Hat® Ansible® Automation Platform. (Red Hat® Ansible® Automation Platform を使用してネットワーク全体を調整します)」

en: Incorrect: "Ansible your entire network."
ja: 誤った使用方法: Ansible your entire network.

en: Never modify a trademark to a plural form. Instead, change the generic word from the singular to the plural.
ja: 商標を複数形に変更しないでください。代わりに、一般的な単語を単数形から複数形に変更します。

en: Correct: "Corporate demand for Red Hat® Ansible® Automation Platform software is surging."
ja: 正しい使用方法: 「Corporate demand for Red Hat® Ansible® Automation Platform software is surging. (Red Hat® Ansible® Automation Platform ソフトウェアに対する企業の需要が急増しています)」

en: Incorrect: "Corporate demand for Ansible is surging."
ja: 誤った使用方法: Corporate demand for Ansible is surging.

en: Never modify a trademark from its possessive form, or make a trademark possessive. Always use it in the form it has been registered.
ja: 商標を所有格から変更したり、商標を所有格にしたりしないでください。必ず登録した形を使用してください。

en: Never translate a trademark into another language.
ja: 商標を別の言語に翻訳しないでください。

en: Never use trademarks to coin new words or names.
ja: 商標を使用して新しい単語や名前を作成しないでください。

en: Never use trademarks to create a play on words.
ja: 商標を使用して言葉遊びを作成しないでください。

en: Never alter a trademark in any way including through unapproved fonts or visual identifiers.
ja: 未承認のフォントや視覚的な識別子など、いかなる方法でも商標を変更しないでください。

en: Never abbreviate or use any Ansible trademarks as an acronym.
ja: Ansible の商標を省略したり、頭文字だけ使用しないでください。

en: The importance of Ansible trademarks
ja: Ansible 商標の重要性

en: The Ansible trademark and the "A" logo in a shaded circle are our most valuable assets. The value of these trademarks encompass the Ansible Brand. Effective trademark use is more than just a name, it defines the level of quality the customer will receive and it ties a product or service to a corporate image. A trademark may serve as the basis for many of our everyday decisions and choices. The Ansible Brand is about how we treat customers and each other. In order to continue to build a stronger more valuable Brand we must use it in a clear and consistent manner.
ja: Ansible の商標と、斜線で囲まれた「A」のロゴは、当社の最も価値のある資産です。これらの商標の価値は、Ansible ブランドを包括するものです。効果的な商標の使用は、単なる名前ではなく、お客様が受け取る品質レベルを定義し、製品やサービスを企業イメージに結びつけるものです。商標は、私たちの日常的な意思決定や選択の多くの基礎となるものです。Ansible ブランドは、私たちがお客様と互いにどのように接するかということです。より強力で価値のあるブランドを構築し続けるためには、明確で一貫した方法で使用しなければなりません。

en: The mark consists of the letter "A" in a shaded circle. As of 5/11/15, this was a pending trademark (registration in process).
ja: このマークは、影付きの円で囲まれた文字「A」で構成されています。2015 年 5 月 11 日の時点で、この商標は係属中 (登録手続き中) でした。

en: Common Ansible Trademarks
ja: 一般的な Ansible の商標

en: Other Common Trademarks and Resource Sites:
ja: その他の一般的な商標およびリソースのサイト:

en: Linux is a registered trademark of Linus Torvalds.
ja: Linux は、Linus Torvalds の登録商標です。

en: UNIX® is a registered trademark of The Open Group.
ja: UNIX® は、The Open Group の登録商標です。

en: Voice Style
ja: 態のスタイル

en: The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one.
ja: Ansible ライティングスタイルの特長は、自然に一緒に流れる短い文です。文法構造は混在させます。文の主題を変化させます。読者に直接話しかけます。質問します。読者が短い文章のペースに順応したら、長い文章を書いてください。

en: Write how real people speak...
ja: 実際のユーザーが話すように記述します。

en: ...but try to avoid slang and colloquialisms that might not translate well into other languages.
ja: ただし、他言語に適切に翻訳できない可能性のある俗語や口語表現は避けるようにしてください。

en: Say big things with small words.
ja: 小さなことばで大きなことを説明します。

en: Be direct. Tell the reader exactly what you want them to do.
ja: 直接的な表現を使用してください。読み手が実行する必要がある内容を正確に指示します。

en: Be honest.
ja: 誠実に表現します。

en: Short sentences show confidence.
ja: 短い文章は自信を示しています。

en: Grammar rules are meant to be bent, but only if the reader knows you are doing this.
ja: 文法規則は、それは読者が何を説明しているかを理解している場合に限り組み込まれることが意図されています。

en: Choose words with fewer syllables for faster reading and better understanding.
ja: 読みやすく、理解を深めるために、音節が少ない単語を選んでください。

en: Think of copy as one-on-one conversations rather than as a speech. It's more difficult to ignore someone who is speaking to you directly.
ja: コピーは、聴衆に対するスピーチではなく、1 対 1 の対話と考えてください。直接話しかけている人を無視するのはより困難です。

en: When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth.
ja: 可能な場合は、タスク指向の文章 (ユーザーによる作業を指示する項目) は、動作を示す用語で開始します。たとえば、「Find software...」、「Contact support...」、「Install the media...」などです。

en: Active Voice
ja: 能動態

en: Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. Also avoid future tense (or using the term "will") whenever possible For example, future tense ("The screen will display...") does not read as well as an active voice ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
ja: 可能な限り、受動態 (「Linuxconf can be started by typing...」) ではなく、能動態 (「Start Linuxconf by typing...」) を使用してください。能動態の方がより生き生きとした、注意を引き付ける文章になります。また、未来形 (または「will」の使用) は可能な限り使用しないでください。たとえば、未来形 (「The screen will display...」) と能動態 (「The screen displays」) では、ニュアンスが異なります。読者は、システムの使用前または使用後ではなく、システムの使用中にドキュメントを参照することがほとんどであることに注意してください。

en: Why Use a Style Guide?
ja: スタイルガイドを使用する理由

en: Style guides are important because they ensure consistency in the content, look, and feel of a book or a website.
ja: スタイルガイドは、ドキュメントまたは Web サイトのコンテンツおよびルックアンドフィールの一貫性を確保するために重要です。

en: Remember, a style guide is only useful if it is used, updated, and enforced.  Style Guides are useful for engineering-related documentation, sales and marketing materials, support docs, community contributions, and more.
ja: スタイルガイドは、使用、更新、および実施される場合にのみ役立つことに注意してください。スタイルガイドは、エンジニアリング関連のドキュメント、営業およびマーケティング用資料、サポートドキュメント、コミュニティーへの貢献などに役立ちます。

en: As changes are made to the overall Ansible site design, be sure to update this style guide with those changes. Or, should other resources listed below have major revisions, consider including company information here for ease of reference.
ja: Ansible サイトのデザイン全体に変更が加えられた場合は、その変更に合わせて本スタイルガイドも更新してください。または、以下に記載されているその他の資料に大幅な改訂がある場合は、参照しやすいようにここに会社情報を含めることを検討してください。

en: This style guide incorporates current Ansible resources and information so that overall site and documentation consistency can be met.
ja: このスタイルガイドには、現在の Ansible リソースと情報が組み込まれているため、サイトとドキュメント全体の一貫性を保つことができます。

en: Testing Ansible
ja: Ansible のテスト

en: Why test your Ansible contributions?
ja: Ansible への貢献をテストする理由

en: If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development.  Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable.
ja: 開発者にとって、最も価値のあることの 1 つが、GitHub の問題を確認し、バグ修正を手伝うことです。バグ修正は、ほとんど常に、機能開発よりも優先されるためです。開発者ではなくても、バグの修正や機能のプル要求のテストを手伝うことは非常に価値のあることです。

en: Ansible users who understand how to write playbooks and roles should be able to test their work.  GitHub pull requests will automatically run a variety of tests (for example, Azure Pipelines) that show bugs in action.  However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged.
ja: Ansible ユーザーは、Playbook とロールの作成方法を理解していれば、自身が作成した作業をテストできるはずです。GitHub プル要求は、バグの動作を示すさまざまなテスト (Azure Pipeline など) を自動的に実行します。ただし、貢献者は、自動化された GitHub チェック以外でも自身の作業をテストし、その証拠を PR で示すと、その作業がレビューされてマージされる可能性が高くなります。

en: Read on to learn how Ansible is tested, how to test your contributions locally, and how to extend testing capabilities.
ja: Ansible のテスト方法、貢献をローカルでテストする方法、およびテスト機能を拡張する方法を説明します。

en: If you want to learn about testing collections, read :ref:`testing_collections`
ja: コレクションのテストを確認する場合は、「:ref:`testing_collections`」を参照してください。

en: Types of tests
ja: テストの種類

en: At a high level we have the following classifications of tests:
ja: テストは、大きく分けて以下のように分類されます。

en: compile
ja: コンパイル

en: Test python code against a variety of Python versions.
ja: さまざまな Python バージョンに対して python コードをテストします。

en: sanity
ja: 健全性

en: Sanity tests are made up of scripts and tools used to perform static code analysis.
ja: 健全性テストは、静的コード分析の実行に使用されるスクリプトおよびツールで構成されています。

en: The primary purpose of these tests is to enforce Ansible coding standards and requirements.
ja: これらのテストの主な目的は、Ansible コーディングの仕様および要件を適用することです。

en: integration
ja: 統合

en: Functional tests of modules and Ansible core functionality.
ja: モジュールおよび Ansible コア機能の機能テスト

en: units
ja: ユニット

en: Tests directly against individual parts of the code base.
ja: コードベースの個々の部分に対して直接テストを行います。

en: If you're a developer, one of the most valuable things you can do is look at the GitHub issues list and help fix bugs.  We almost always prioritize bug fixing over feature development.
ja: 開発者にとって、最も価値のあることの 1 つが、GitHub の問題を確認し、バグ修正を手伝うことです。バグ修正は、ほとんど常に、機能開発よりも優先されるためです。

en: Even for non developers, helping to test pull requests for bug fixes and features is still immensely valuable.  Ansible users who understand writing playbooks and roles should be able to add integration tests and so GitHub pull requests with integration tests that show bugs in action will also be a great way to help.
ja: 開発者ではなくても、バグの修正や機能のプル要求のテストを手伝うことは非常に価値のあることです。Ansible ユーザーが Playbook やロールの記述方法を熟知していれば統合テストを追加できるため、バグが実際に動かしている様子を示す統合テストが付いた GitHub プル要求も、大きな助けになるでしょう。

en: Testing within GitHub & Azure Pipelines
ja: GitHub および Azure Pipeline でのテスト

en: Organization
ja: 組織

en: When Pull Requests (PRs) are created they are tested using Azure Pipelines, a Continuous Integration (CI) tool. Results are shown at the end of every PR.
ja: プル要求 (PR: Pull Requests) が作成されると、継続的統合 (CI) ツールである Azure Pipeline を使用してテストが行われます。結果はすべての PR の最後に表示されます。

en: When Azure Pipelines detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example::
ja: Azure Pipeline がエラーを検出し、それが PR で変更されたファイルにリンクされると、関連する行が GitHub のコメントとして追加されます。たとえば、以下のようになります。

en: From the above example we can see that ``--test pep8`` and ``--test validate-modules`` have identified an issue. The commands given allow you to run the same tests locally to ensure you've fixed all issues without having to push your changes to GitHub and wait for Azure Pipelines, for example:
ja: 上記の例から、``--test pep8`` および ``--test validate-modules`` が問題を特定したことが分かります。指定されたコマンドを使用すると、同じテストをローカルで実行して、変更を GitHub にプッシュして Azure Pipeline を待つことなく、すべての問題を修正したことを確認できます。次に例を示します。

en: If you haven't already got Ansible available, use the local checkout by running::
ja: Ansible がまだ利用できるようになっていない場合は、ローカルでチェックアウトを実行してください。

en: Then run the tests detailed in the GitHub comment::
ja: 次に、GitHub コメントで説明するテストを実行します。

en: If there isn't a GitHub comment stating what's failed you can inspect the results by clicking on the "Details" button under the "checks have failed" message at the end of the PR.
ja: GitHub のコメントに何が失敗したかが書かれていない場合は、PR の末尾にある「checks have failed」というメッセージの下にある「Details」ボタンをクリックして結果を確認することができます。

en: Rerunning a failing CI job
ja: 失敗した CI ジョブの再実行

en: Occasionally you may find your PR fails due to a reason unrelated to your change. This could happen for several reasons, including:
ja: 時折、変更とは関係のない理由で PR が失敗することがあります。これには、以下のような理由が考えられます。

en: a temporary issue accessing an external resource, such as a yum or git repo
ja: yum や git リポジトリーなどの外部リソースにアクセスする際に一時的に問題が発生した場合。

en: a timeout creating a virtual machine to run the tests on
ja: テストを実行するための仮想マシンを作成するタイムアウト。

en: If either of these issues appear to be the case, you can rerun the Azure Pipelines test by:
ja: これらの問題のいずれかがケースとして表示される場合は、以下を実行して Azure Pipelines テストを再実行できます。

en: adding a comment with ``/rebuild`` (full rebuild) or ``/rebuild_failed`` (rebuild only failed CI nodes) to the PR
ja: ``/rebuild`` (完全な再構築) または ``/rebuild_failed`` (構築に失敗した CI ノードのみの再構築) でのコメントの追加

en: closing and re-opening the PR (full rebuild)
ja: PR を閉じて再度開く (完全な再構築)

en: making another change to the PR and pushing to GitHub
ja: PR に何らかの変更を加えて GitHub にプッシュする

en: If the issue persists, please contact us in the ``#ansible-devel`` irc channel on the `irc.libera.chat <https://libera.chat/>`_ IRC network.
ja: 問題が解決しない場合は、IRC ネットワーク `irc.libera.chat <https://libera.chat/>` における IRC チャンネル ``#ansible-devel`` までお問い合わせください。

en: How to test a PR
ja: PR をテストする方法

en: Ideally, code should add tests that prove that the code works. That's not always possible and tests are not always comprehensive, especially when a user doesn't have access to a wide variety of platforms, or is using an API or web service. In these cases, live testing against real equipment can be more valuable than automation that runs against simulated interfaces. In any case, things should always be tested manually the first time as well.
ja: 理想的には、コードが機能することを証明するテストを追加することが推奨されます。特に、ユーザーが様々なプラットフォームにアクセスできない場合、または API や Web サービスを使用している場合は、これが必ずしも可能ではなく、テストも必ずしも包括的ではありません。このような場合は、シミュレーションされたインターフェースに対して実行される自動化よりも、実際の機器を使用したライブテストの方が有益となります。いずれにせよ、最初の段階でも常に手動でテストする必要があります。

en: Thankfully, helping to test Ansible is pretty straightforward, assuming you are familiar with how Ansible works.
ja: Ansible の動作を熟知していれば、Ansible のテストを手伝うことは非常に簡単です。

en: Setup: Checking out a Pull Request
ja: 設定: プル要求のチェックアウト

en: You can do this by:
ja: これは、以下の方法で実行できます。

en: checking out Ansible
ja: Ansible のチェックアウト

en: fetching the proposed changes into a test branch
ja: 提案された変更をテストブランチに取得

en: testing
ja: テスト

en: commenting on that particular issue on GitHub
ja: GitHub に特定の問題についてのコメント

en: Here's how:
ja: 以下に、実行する方法を説明します。

en: Testing source code from GitHub pull requests sent to us does have some inherent risk, as the source code sent may have mistakes or malicious code that could have a negative impact on your system. We recommend doing all testing on a virtual machine, whether a cloud instance, or locally.  Some users like Vagrant or Docker for this, but they are optional. It is also useful to have virtual machines of different Linux or other flavors, since some features (for example, package managers such as apt or yum) are specific to those OS versions.
ja: GitHub のプル要求から送られてきたソースコードをテストすることにはリスクが伴います。送られてきたソースコードには、間違いや悪意のあるコードが含まれていて、システムに影響を及ぼす可能性があるからです。すべてのテストは、仮想マシン上で行うことが推奨されます。クラウドインスタンスでもローカルでもかまいません。このために Vagrant や Docker を好むユーザーもいますが、これらは任意です。また、いくつかの機能 (たとえば、apt や yum などのパッケージマネージャー) は、それらの OS バージョンに固有のものであるため、異なる Linux やその他のフレーバーの仮想マシンを用意しておくと便利です。

en: Create a fresh area to work::
ja: 作業用に新しい領域を作成します。

en: Next, find the pull request you'd like to test and make note of its number. It will look something like this::
ja: 次に、テストするプル要求を見つけて、その番号を書き留めます。次のようになります。

en: Only test ``ansible:devel``
ja: ``ansible:devel`` のみをテストします。

en: It is important that the PR request target be ``ansible:devel``, as we do not accept pull requests into any other branch. Dot releases are cherry-picked manually by Ansible staff.
ja: 他のブランチへのプル要求は使用できないため、PR 要求のターゲットは ``ansible:devel`` にすることが重要です。ドットリリースは、Ansible のスタッフが入念に選択しています。

en: Use the pull request number when you fetch the proposed changes and create your branch for testing::
ja: 提案された変更を取得し、テスト用にブランチを作成するときにプル要求番号を使用します。

en: The first command fetches the proposed changes from the pull request and creates a new branch named ``testing_PRXXXX``, where the XXXX is the actual number associated with the pull request (for example, 65381). The second command checks out the newly created branch.
ja: 1 つ目のコマンドはプル要求から提案された変更を取得し、``testing_PRXXXX`` という名前の新規ブランチを作成します。XXXX はプル要求に関連する実際の番号 (例: 65381) です。2 つ目のコマンドは、新たに作成されたブランチをチェックアウトします。

en: If the GitHub user interface shows that the pull request will not merge cleanly, we do not recommend proceeding if you are not somewhat familiar with git and coding, as you will have to resolve a merge conflict. This is the responsibility of the original pull request contributor.
ja: GitHub ユーザーインターフェースで、プル要求が正常にマージされないと示された場合は、マージの競合を解決しなければならないため、git およびコーディングにあまり精通していない場合は、続行しないことが推奨されます。これは、元のプル要求の投稿者の責任です。

en: Some users do not create feature branches, which can cause problems when they have multiple, unrelated commits in their version of ``devel``. If the source looks like ``someuser:devel``, make sure there is only one commit listed on the pull request.
ja: 一部のユーザーは機能ブランチを作成しないため、``devel`` のバージョンに関連性のないコミットが複数ある場合に、問題が発生する可能性があります。ソースが ``someuser:devel`` のように表示される場合は、プル要求に記載されているコミットが 1 つだけであることを確認してください。

en: The Ansible source includes a script that allows you to use Ansible directly from source without requiring a full installation that is frequently used by developers on Ansible.
ja: Ansible のソースには、Ansible の開発者が頻繁に使用するフルインストールを必要とせず、ソースから直接 Ansible を使用するようにするスクリプトが含まれています。

en: Simply source it (to use the Linux/Unix terminology) to begin using it immediately::
ja: ソースを作成するだけ (Linux/Unix の用語を使用するために) で、すぐに使い始めることができます。

en: This script modifies the ``PYTHONPATH`` environment variables (along with a few other things), which will be temporarily set as long as your shell session is open.
ja: このスクリプトは、``PYTHONPATH`` 環境変数を変更します (他にもいくつかあります)。これは、シェルセッションが開いている間は一時的に設定されます。

en: Testing the Pull Request
ja: プル要求のテスト

en: At this point, you should be ready to begin testing!
ja: この時点でテストを開始する準備が整いました。

en: Some ideas of what to test are:
ja: 何をテストするかのアイデアをいくつか挙げてみましょう。

en: Create a test Playbook with the examples in and check if they function correctly
ja: 例題を含むテスト Playbook を作成し、それらが正しく機能するかどうかを確認します。

en: Test to see if any Python backtraces returned (that's a bug)
ja: Python のバックトレースが返されているかどうかをテストします (これはバグです)。

en: Test on different operating systems, or against different library versions
ja: 異なるオペレーティングシステムで、または異なるバージョンのライブラリーに対してテストを行います。

en: Run sanity tests
ja: 健全性テストの実行

en: More information: :ref:`testing_sanity`
ja: 詳細情報: :ref:`testing_sanity`

en: Run unit tests
ja: ユニットテストの実行

en: More information: :ref:`testing_units`
ja: 詳細情報: :ref:`testing_units`

en: Run integration tests
ja: 統合テストの実行

en: More information: :ref:`testing_integration`
ja: 詳細情報: :ref:`testing_integration`

en: Any potential issues should be added as comments on the pull request (and it's acceptable to comment if the feature works as well), remembering to include the output of ``ansible --version``
ja: 潜在的な問題があれば、プル要求にコメントを追加する必要があります (機能が正常に動作する場合もコメントしてもかまいません)。忘れずに ``ansible --version`` の出力を転載してください。

en: Example::
ja: 例:

en: If the PR does not resolve the issue, or if you see any failures from the unit/integration tests, just include that output instead:
ja: PR が問題を解決しない場合や、ユニット/統合テストでエラーが発生した場合は、代わりにその出力を転載してください。

en: This change causes errors for me.
ja: この変更により、エラーが発生します。

en: Code Coverage Online
ja: オンラインのコードカバレージ

en: `The online code coverage reports <https://codecov.io/gh/ansible/ansible>`_ are a good way to identify areas for testing improvement in Ansible.  By following red colors you can drill down through the reports to find files which have no tests at all.  Adding both integration and unit tests which show clearly how code should work, verify important Ansible functions and increase testing coverage in areas where there is none is a valuable way to help improve Ansible.
ja: `オンラインコードカバレージレポート <https://codecov.io/gh/ansible/ansible>`_ は、Ansible でテストが向上する領域を特定するのが適切な方法です。赤い色に従うことで、レポートを掘り下げて、テストがまったくないファイルを見つけることができます。コードがどのように機能するかを明確に示す統合テストとユニットテストの両方を追加し、重要な Ansible 関数を検証し、存在しない領域でテスト範囲を拡大することは、Ansible の改善に役立つ貴重な方法です。

en: The code coverage reports only cover the ``devel`` branch of Ansible where new feature development takes place.  Pull requests and new code will be missing from the codecov.io coverage reports so local reporting is needed.  Most ``ansible-test`` commands allow you to collect code coverage, this is particularly useful to indicate where to extend testing. See :ref:`testing_running_locally` for more information.
ja: コードカバレッジレポートは、新しい機能開発が行われる Ansible の ``devel`` ブランチのみを対象とします。プル要求および新規コードは codecov.io のカバレッジレポートに含まれないため、ローカルレポートが必要になるようです。ほとんどの ``ansible-test`` コマンドでは、コードカバレッジを収集できます。これは、テストを拡張する場所を示すのに特に役に立ちます。詳細は、「:ref:`testing_running_locally`」を参照してください。

en: Want to know more about testing?
ja: テストに関する詳細情報

en: If you'd like to know more about the plans for improving testing Ansible then why not join the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
ja: Ansible テストを改善する詳細な計画を確認したい場合は、`テストワーキンググループ <https://github.com/ansible/community/blob/master/meetings/README.md>`_ にご参加ください。

en: Each action plugin should have a matching module of the same name to provide documentation.
ja: 各アクションプラグインには、ドキュメントを提供するモジュールと同じ名前のモジュールが必要です。

en: Verifies that ``ansible-doc`` can parse module documentation on all supported Python versions.
ja: ``ansible-doc`` が、サポートされているすべての Python バージョンでモジュールドキュメントを解析できることを確認します。

en: ``test/lib/ansible_test/_data/requirements/sanity.import-plugins.txt`` must be an identical copy of ``requirements.txt`` found in the project's root.
ja: ``test/lib/ansible_test/_data/requirements/sanity.import-plugins.txt`` は、プロジェクトのルートにある ``requirements.txt`` と同じコピーである必要があります。

en: Check the order of precedence for Ansible variables against :ref:`ansible_variable_precedence`.
ja: 「:ref:`ansible_variable_precedence`」で、Ansible 変数の優先順位の順序を確認します。

en: Update the Azure integration test requirements file when changes are made to the Azure packaging requirements file:
ja: Azure パッケージ化の要件ファイルに変更が加えられたら、Azure 統合テスト要件ファイルを更新します。

en: The ``bin/`` directory in Ansible must contain only symbolic links to executable files. These files must reside in the ``lib/ansible/`` or ``test/lib/ansible_test/`` directories.
ja: Ansible の ``bin/`` ディレクトリーには、実行ファイルへのシンボリックリンクのみが含まれている必要があります。これらのファイルは、``lib/ansible/`` ディレクトリーまたは ``test/lib/ansible_test/`` ディレクトリーに置かれている必要があります。

en: This is required to allow ``ansible-test`` to work with containers and remote hosts when running from an installed version of Ansible.
ja: これは、インストール済みバージョンの Ansible から実行する際に、``ansible-test`` がコンテナーおよびリモートホストで動作できるようにするために必要です。

en: Symlinks for each entry point in ``bin/`` must also be present in ``test/lib/ansible_test/_data/injector/``. Each symlink should point to the ``python.py`` script in the same directory. This facilitates running with the correct Python interpreter and enabling code coverage.
ja: ``bin/`` の各エントリーポイントのシンボリックリンクも ``test/lib/ansible_test/_data/injector/`` に存在する必要があります。それぞれのシンボリックリンクは同じディレクトリー内の ``python.py`` スクリプトを指定する必要があります。これにより、正しい Python インタープリターでの実行とコードのカバレッジの有効化が容易になります。

en: Most Python files should include the following boilerplate:
ja: ほとんどの Python ファイルには以下の boilerplate が必要です。

en: Verifies that ``./github/BOTMETA.yml`` is valid.
ja: ``./github/BOTMETA.yml`` が有効であることを確認します。

en: Basic linting of changelog fragments with `antsibull-changelog lint <https://pypi.org/project/antsibull-changelog/>`_.
ja: `antsibull-changelog lint <https://pypi.org/project/antsibull-changelog/>`_ を使用した changelog フラグメントの基本的な文法チェックです。

en: One or more of the following sections are required:
ja: 以下のセクションが 1 つ以上必要です。

en: New modules and plugins must not be included in changelog fragments.
ja: 新しいモジュールおよびプラグインは、changelog フラグメントに含めることができません。

en: See :ref:`testing_compile` for more information.
ja: 詳細は、「:ref:`testing_compile`」を参照してください。

en: The file ``examples/scripts/ConfigureRemotingForAnsible.ps1`` is required and must be a regular file. It is used by external automated processes and cannot be moved, renamed or replaced with a symbolic link.
ja: ``examples/scripts/ConfigureRemotingForAnsible.ps1`` ファイルは必須であり、通常のファイルである必要があります。これは外部の自動化プロセスによって使用され、移動したり、名前を変更したり、シンボリックリンクに置き換えたりすることはできません。

en: deprecated-config
ja: 非推奨の設定

en: ``DOCUMENTATION`` config is scheduled for removal
ja: ``DOCUMENTATION`` 設定は削除される予定です。

en: Verifies that ``make singlehtmldocs`` in ``docs/docsite/`` completes without errors.
ja: ``docs/docsite/`` の ``make singlehtmldocs`` が完了し、エラーがないことを確認します。

en: The ``__init__.py`` files under the following directories must be empty.  For some of these (modules and tests), ``__init__.py`` files with code won't be used.  For others (module_utils), we want the possibility of using Python namespaces which an empty ``__init__.py`` will allow for.
ja: 以下のディレクトリーにある ``__init__.py`` ファイルは空である必要があります。これらのディレクトリーの一部 (モジュールおよびテスト) では、コードを持つ ``__init__.py`` ファイルは使用されません。その他 (モジュールユーティリティー) の場合は、空の ``__init__.py`` を許可する Python 名前空間を使用することも可能です。

en: Most Python files should include the following boilerplate at the top of the file, right after the comment header:
ja: ほとんどの Python ファイルには、ファイルの上部、コメントヘッダーの直後に次の boilerplate を含める必要があります。

en: This uses Python 3 semantics for absolute vs relative imports, division, and print.  By doing this, we can write code which is portable between Python 2 and Python 3 by following the Python 3 semantics.
ja: ここでは、絶対的インポートと相対的インポート、除算、および出力に Python 3 セマンティクスを使用します。Python 3 セマンティクスに従って、Python 2 と Python 3 の間で移植可能なコードを作成できます。

en: When Python 2 encounters an import of a name in a file like ``import copy`` it attempts to load ``copy.py`` from the same directory as the file is in.  This can cause problems if there is a python file of that name in the directory and also a python module in ``sys.path`` with that same name.  In that case, Python 2 would load the one in the same directory and there would be no way to load the one on ``sys.path``.  Python 3 fixes this by making imports absolute by default.  ``import copy`` will find ``copy.py`` from ``sys.path``.  If you want to import ``copy.py`` from the same directory, the code needs to be changed to perform a relative import: ``from . import copy``.
ja: Python 2 は、``import copy`` のようなファイルで名前の import に遭遇すると、そのファイルがあるディレクトリーから ``copy.py`` を読み込もうとします。これは、そのディレクトリーにその名前の python ファイルがあり、``sys.path`` にも同じ名前の python モジュールがある場合に問題が発生します。この場合、Python 2 は同じディレクトリーにあるものを読み込み、``sys.path`` にあるものを読み込む方法がありません。Python 3 は、デフォルトでインポートを行うようにすることでこの問題を解決しました。``import copy`` は、``sys.path`` から ``copy.py`` を見つけます。同じディレクトリーから ``copy.py`` をインポートする場合は、相対インポートを行うようにコードを変更する必要があります (``from . import copy``)。

en: In Python 2, the division operator (``/``) returns integer values when used with integers.  If there was a remainder, this part would be left off (aka, `floor division`).  In Python 3, the division operator (``/``) always returns a floating point number.  Code that needs to calculate the integer portion of the quotient needs to switch to using the floor division operator (`//`) instead.
ja: Python 2 では、除算演算子 (``/``) は、整数と共に使用すると整数値を返します。残りの部分がある場合、この部分はオフ (別名 `切り捨て除算`) のままにします。Python 3 では、除算演算子 (``/``) は常に浮動小数点数を返します。引用符で整数を計算する必要のあるコードは、代わりに切り捨て除算演算子 (`//`) の使用に切り替える必要があります。

en: In Python 2, :func:`python:print` is a keyword.  In Python 3, :func:`python3:print` is a function with different parameters.  Using this ``__future__`` allows using the Python 3 print semantics everywhere.
ja: Python 2 では、:func:`python:print` はキーワードです。Python 3 では、 :func:`python3:print` は異なるパラメーターを持つ機能です。この ``__future__`` を使用すると、あらゆる場所に Python 3 出力セマンティクスを使用できます。

en: ignores
ja: ignore

en: Sanity tests for individual files can be skipped, and specific errors can be ignored.
ja: 個々のファイルで健全性テストをスキップしたり、特定のエラーを無視したりできます。

en: When to Ignore Errors
ja: エラーを無視するタイミング

en: Sanity tests are designed to improve code quality and identify common issues with content. When issues are identified during development, those issues should be corrected.
ja: 健全性テストは、コードの品質を改善し、コンテンツに関する典型的な問題を特定するように設計されています。開発中に問題を特定する際に、問題を修正する必要があります。

en: As development of Ansible continues, sanity tests are expanded to detect issues that previous releases could not. To allow time for existing content to be updated to pass newer tests, ignore entries can be added. New content should not use ignores for existing sanity tests.
ja: Ansible の開発が続くにつれて、健全性テストが拡張され、以前のリリースでは検出できなかった問題が検出されます。既存のコンテンツを更新して新しいテストに合格するための時間を確保するために、ignore エントリーを追加できます。新しいコンテンツでは、既存の健全性テストで ignore を使用しないでください。

en: When code is fixed to resolve sanity test errors, any relevant ignores must also be removed. If the ignores are not removed, this will be reported as an unnecessary ignore error. This is intended to prevent future regressions due to the same error recurring after being fixed.
ja: コードが修正されて健全性テストエラーを解決する場合には、関連する ignore も削除する必要があります。ignore が削除されないと、不要な ignore エラーが報告されます。これは、修正後に同じエラーが繰り返し発生するため、今後のリグレッションを防ぐことを目的としています。

en: When to Skip Tests
ja: テストをスキップするタイミング

en: Although rare, there are reasons for skipping a sanity test instead of ignoring the errors it reports.
ja: 頻繁には起こりませんが、報告されたエラーを無視する代わりに、健全性テストを行わない (スキップする) 場合があります。

en: If a sanity test results in a traceback when processing content, that error cannot be ignored. If this occurs, open a new `bug report <https://github.com/ansible/ansible/issues/new?template=bug_report.md>`_ for the issue so it can be fixed. If the traceback occurs due to an issue with the content, that issue should be fixed. If the content is correct, the test will need to be skipped until the bug in the sanity test is fixed.
ja: 健全性テストにより、コンテンツの処理時にトレースバックが発生すると、そのエラーは無視できません。このような場合には、新しい `バグレポート <https://github.com/ansible/ansible/issues/new?template=bug_report.md>`_ を作成し、問題を修正してください。コンテンツに問題があるためにトレースバックが発生した場合は、その問題を修正する必要があります。コンテンツが正しい場合は、健全性テストのバグが修正されるまで、テストをスキップする必要があります。

en: Caution should be used when skipping sanity tests instead of ignoring them. Since the test is skipped entirely, resolution of the issue will not be automatically detected. This will prevent prevent regression detection from working once the issue has been resolved. For this reason it is a good idea to periodically review skipped entries manually to verify they are required.
ja: 健全性テストを無視するのではなくスキップする場合は注意が必要です。テストは完全にスキップされるため、問題の解決が自動的に検出されません。これにより、問題が解決すると回帰検出が機能しなくなります。このため、スキップしたエントリーを定期的に手動で確認して、そのエントリーが必要かどうかを確認することが推奨されます。

en: Ignore File Location
ja: ignore ファイルの場所

en: The location of the ignore file depends on the type of content being tested.
ja: ignore ファイルの場所は、テストするコンテンツの種類によって異なります。

en: Ansible Collections
ja: Ansible コレクション

en: Since sanity tests change between Ansible releases, a separate ignore file is needed for each Ansible major release.
ja: 健全性テストは Ansible リリース間で異なるため、Ansible メジャーリリースごとに個別の ignore ファイルが必要です。

en: The filename is ``tests/sanity/ignore-X.Y.txt`` where ``X.Y`` is the Ansible release being used to test the collection.
ja: ファイル名は ``tests/sanity/ignore-X.Y.txt`` です。``X.Y`` は、コレクションをテストするために使用される Ansible リリースです。

en: Maintaining a separate file for each Ansible release allows a collection to pass tests for multiple versions of Ansible.
ja: Ansible リリースごとに個別のファイルを維持すると、コレクションが Ansible の複数のバージョンのテストに合格できるようになります。

en: When testing Ansible, all ignores are placed in the ``test/sanity/ignore.txt`` file.
ja: Ansible をテストする際、すべての ignore は ``test/sanity/ignore.txt`` ファイルに置かれます。

en: Only a single file is needed because ``ansible-test`` is developed and released as a part of Ansible itself.
ja: ``ansible-test`` が作成され、Ansible 自体の一部としてリリースされるため、単一のファイルのみが必要になります。

en: Ignore File Format
ja: ignore ファイル形式

en: The ignore file contains one entry per line. Each line consists of two columns, separated by a single space. Comments may be added at the end of an entry, started with a hash (``#``) character, which can be proceeded by zero or more spaces. Blank and comment only lines are not allowed.
ja: ignore ファイルでは、1 行に 1 つのエントリーが含まれます。各行は、1 つのスペースで区切られた 2 つの列で構成されます。コメントはエントリーの末尾に追加できます。先頭にハッシュ (``#``) 文字を付けて、ゼロ以上の空白を追加できます。空白とコメントのみの行は使用できません。

en: The first column specifies the file path that the entry applies to. File paths must be relative to the root of the content being tested. This is either the Ansible source or an Ansible collection. File paths cannot contain a space or the hash (``#``) character.
ja: 最初の列は、エントリーが適用されるファイルパスを指定します。ファイルパスは、テストするコンテンツのルートに対して相対的である必要があります。これは Ansible ソースまたは Ansible コレクションのいずれかです。ファイルパスにスペースまたはハッシュ (``#``) 文字を含めることはできません。

en: The second column specifies the sanity test that the entry applies to. This will be the name of the sanity test. If the sanity test is specific to a version of Python, the name will include a dash (``-``) and the relevant Python version. If the named test uses error codes then the error code to ignore must be appended to the name of the test, separated by a colon (``:``).
ja: 2 列目は、エントリーが適用される健全性テストを指定します。これが健全性テストの名前になります。Python のバージョンに固有の健全性テストを使用する場合は、名前にダッシュ (``-``) と関連する Python バージョンが含まれます。名前付きテストがエラーコードを使用する場合は、無視するエラーコードをコロン (``:``) で区切ってテストの名前に追加する必要があります。

en: Below are some example ignore entries for an Ansible collection::
ja: 以下の例は、Ansible コレクションの ignore エントリーの例です。

en: It is also possible to skip a sanity test for a specific file. This is done by adding ``!skip`` after the sanity test name in the second column. When this is done, no error code is included, even if the sanity test uses error codes.
ja: 特定ファイルの健全性テストをスキップすることもできます。これは、2 番目のコラムの健全性テスト名の後に ``!skip`` を追加することで行います。これを行うと、健全性テストでエラーコードを使用しても、エラーコードは含まれません。

en: Below are some example skip entries for an Ansible collection::
ja: 以下は、Ansible コレクションのエントリーをスキップする例です。

en: Ignore File Errors
ja: ignore ファイルエラー

en: There are various errors that can be reported for the ignore file itself:
ja: ignore ファイル自体について報告できるさまざまなエラーがあります。

en: syntax errors parsing the ignore file
ja: ignore ファイルを解析する構文エラー

en: references a file path that does not exist
ja: 存在しないファイルパスを参照

en: references to a sanity test that does not exist
ja: 存在しない健全性テストへの参照

en: ignoring an error that does not occur
ja: 発生しないエラーを無視

en: ignoring a file which is skipped
ja: スキップされたファイルを無視

en: duplicate entries
ja: 重複エントリー

en: Ansible allows unchecked imports of some libraries from specific directories, listed at the bottom of this section. Import all other Python libraries in a try/except ImportError block to support sanity tests such as ``validate-modules`` and to allow Ansible to give better error messages to the user. To import a library in a try/except ImportError block:
ja: Ansible では、このセクションの下部に記載されている特定のディレクトリーから、いくつかのライブラリーを確認せずにインポートすることができます。``validate-modules`` などの健全性テストをサポートし、Ansible がユーザーに適切なエラーメッセージを表示できるようにするため、try/except ImportError ブロックで他のすべての Python ライブラリーをインポートします。try/except ImportError ブロックでライブラリをインポートするには、次を行います。

en: In modules:
ja: モジュールの場合:

en: In plugins:
ja: プラグインの場合:

en: Ansible allows the following unchecked imports from these specific directories:
ja: Ansible では、これらの特定のディレクトリーから次の未確認インポートを許可します。

en: For ``lib/ansible/modules/`` and ``lib/ansible/module_utils/``, unchecked imports are only allowed from the Python standard library;
ja: ``lib/ansible/modules/`` および ``lib/ansible/module_utils/`` の場合、未確認インポートは Python 標準ライブラリーでのみ利用可能です。

en: For ``lib/ansible/plugins/``, unchecked imports are only allowed from the Python standard library, from dependencies of ansible-core, and from ansible-core itself;
ja: ``lib/ansible/plugins/`` では、未確認インポートは、Python 標準ライブラリー、ansible-core の依存関係、および ansible-core 自体からのみ許可されます。

en: For ``plugins/modules/`` and ``plugins/module_utils/``, unchecked imports are only allowed from the Python standard library;
ja: ``plugins/modules/`` および ``plugins/module_utils/`` の場合、未確認インポートは Python 標準ライブラリーでのみ利用可能です。

en: For other directories in ``plugins/`` (see `the community collection requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins>`_ for a list), unchecked imports are only allowed from the Python standard library, from dependencies of ansible-core, and from ansible-core itself.
ja: ``plugins/`` のその他のディレクトリー (一覧は「`コミュニティーコレクション要件 <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins>`_」を参照) では、未確認インポートは Python 標準ライブラリー、ansible-core の依存関係、および ansible-core 自体からのみ許可されます。

en: Sanity Tests
ja: 健全性テスト

en: The following sanity tests are available as ``--test`` options for ``ansible-test sanity``. This list is also available using ``ansible-test sanity --list-tests --allow-disabled``.
ja: 以下の健全性テストは、``ansible-test sanity`` の ``--test`` オプションとして利用できます。この一覧は、``ansible-test sanity --list-tests --allow-disabled`` を使用しても利用できます。

en: For information on how to run these tests, see :ref:`sanity testing guide <testing_sanity>`.
ja: これらのテストの実行方法は、「:ref:`健全性テストガイド <testing_sanity>`」を参照してください。

en: Integration tests are executed by ``ansible-test`` and reside in directories under ``test/integration/targets/``. Each test MUST have an ``aliases`` file to control test execution.
ja: 統合テストは ``ansible-test`` によって実行し、``test/integration/targets/`` 配下のディレクトリーに置かれます。各テストには、テストの実行を制御する ``aliases`` ファイルが必要です。

en: Aliases are explained in the following sections. Each alias must be on a separate line in an ``aliases`` file.
ja: エイリアスは、以下のセクションで説明します。各エイリアスは、``aliases`` ファイルの別の行に指定する必要があります。

en: Groups
ja: グループ

en: Tests must be configured to run in exactly one group. This is done by adding the appropriate group to the ``aliases`` file.
ja: テストは 1 つのグループで実行するように設定する必要があります。これは、適切なグループを ``aliases`` ファイルに追加することで行われます。

en: The following are examples of some of the available groups:
ja: 利用可能な一部のグループの例を以下に示します。

en: Groups are used to balance tests across multiple CI jobs to minimize test run time. They also improve efficiency by keeping tests with similar requirements running together.
ja: グループは、複数の CI ジョブ間でテストのバランスを取り、テストのランタイムを最小限にするために使用します。同様の要件が一緒に実行されるテストを維持することで、効率性も向上します。

en: When selecting a group for a new test, use the same group as existing tests similar to the one being added. If more than one group is available, select one randomly.
ja: 新規テスト用にグループを選択する場合は、追加する既存のテストと同様のグループを使用します。複数のグループが利用可能な場合は、ランダムに 1 つのグループを選択します。

en: Setup
ja: 設定

en: Aliases can be used to execute setup targets before running tests:
ja: エイリアスは、テストを実行する前に設定ターゲットを実行するのに使用できます。

en: ``setup/once/TARGET`` - Run the target ``TARGET`` before the first target that requires it.
ja: ``setup/once/TARGET`` - それが必要な最初のターゲットの前に、ターゲット ``TARGET`` を実行します。

en: ``setup/always/TARGET`` - Run the target ``TARGET`` before each target that requires it.
ja: ``setup/always/TARGET`` - 必要な各ターゲットの前にターゲット ``TARGET`` を実行します。

en: Aliases can be used to express some test requirements:
ja: エイリアスを使用すると、一部のテスト要件を表現することができます。

en: ``needs/privileged`` - Requires ``--docker-privileged`` when running tests with ``--docker``.
ja: ``needs/privileged`` - ``--docker`` でテストを実行する場合は、``--docker-privileged`` が必要です。

en: ``needs/root`` - Requires running tests as ``root`` or with ``--docker``.
ja: ``needs/root`` - ``root`` または ``--docker`` でテストを実行する必要があります。

en: ``needs/ssh`` - Requires SSH connections to localhost (or the test container with ``--docker``) without a password.
ja: ``needs/ssh`` - パスワードなしで localhost (または ``--docker`` を使用したテストコンテナー) への SSH 接続を必要とします。

en: ``needs/httptester`` - Requires use of the http-test-container to run tests.
ja: ``needs/httptester`` - テストを実行するには、http-test-container を使用する必要があります。

en: Dependencies
ja: 依存関係

en: Some test dependencies are automatically discovered:
ja: 一部のテスト依存関係は自動的に検出されます。

en: Ansible role dependencies defined in ``meta/main.yml`` files.
ja: ``meta/main.yml`` ファイルで定義される Ansible ロールの依存関係。

en: Setup targets defined with ``setup/*`` aliases.
ja: ``setup/*`` エイリアスで定義されたターゲットのセットアップ。

en: Symbolic links from one target to a file in another target.
ja: あるターゲットから別のターゲットのファイルへのシンボリックリンク。

en: Aliases can be used to declare dependencies that are not handled automatically:
ja: エイリアスを使用すると、自動的に処理されない依存関係を宣言できます。

en: ``needs/target/TARGET`` - Requires use of the test target ``TARGET``.
ja: ``needs/target/TARGET`` - テストターゲット ``TARGET`` を使用する必要があります。

en: ``needs/file/PATH`` - Requires use of the file ``PATH`` relative to the git root.
ja: ``needs/file/PATH`` - git ルートと関連するファイル ``PATH`` を使用する必要があります。

en: Skipping
ja: スキップ

en: Aliases can be used to skip platforms using one of the following:
ja: エイリアスを使用すると、以下のいずれかを使用してプラットフォームをスキップできます。

en: ``skip/freebsd`` - Skip tests on FreeBSD.
ja: ``skip/freebsd`` - FreeBSD のテストをスキップします。

en: ``skip/osx`` - Skip tests on macOS.
ja: ``skip/osx`` - macOS でのテストをスキップします。

en: ``skip/rhel`` - Skip tests on RHEL.
ja: ``skip/rhel`` - RHEL でのテストをスキップします。

en: ``skip/docker`` - Skip tests when running in a Docker container.
ja: ``skip/docker`` - Docker コンテナーで実行する場合はテストをスキップします。

en: Platform versions, as specified using the ``--remote`` option with ``/`` removed, can also be skipped:
ja: ``--remote`` オプションで ``/`` を削除して指定したプラットフォームバージョンもスキップできます。

en: ``skip/freebsd11.1`` - Skip tests on FreeBSD 11.1.
ja: ``skip/freebsd11.1`` - FreeBSD 11.1 のテストをスキップします。

en: ``skip/rhel7.6`` - Skip tests on RHEL 7.6.
ja: ``skip/rhel7.6`` - RHEL 7.6 でのテストをスキップします。

en: Windows versions, as specified using the ``--windows`` option can also be skipped:
ja: ``--windows`` オプションを使用して指定する Windows バージョンもスキップできます。

en: ``skip/windows/2008`` - Skip tests on Windows Server 2008.
ja: ``skip/windows/2008`` - Windows Server 2008 のテストをスキップします。

en: ``skip/windows/2012-R2`` - Skip tests on Windows Server 2012 R2.
ja: ``skip/windows/2012-R2`` - Windows Server 2012 R2 のテストをスキップします。

en: Aliases can be used to skip Python major versions using one of the following:
ja: エイリアスを使用すると、以下のいずれかを使用して Python のメジャーバージョンをスキップできます。

en: ``skip/python2`` - Skip tests on Python 2.x.
ja: ``skip/python2`` - Python 2.x のテストをスキップします。

en: ``skip/python3`` - Skip tests on Python 3.x.
ja: ``skip/python3`` - Python 3.x のテストをスキップします。

en: For more fine grained skipping, use conditionals in integration test playbooks, such as:
ja: より詳細なスキップを行うには、統合テストの Playbook で条件を使用します。以下に例を示します。

en: Miscellaneous
ja: その他

en: There are several other aliases available as well:
ja: その他にも利用できるエイリアスがいくつかあります。

en: ``destructive`` - Requires ``--allow-destructive`` to run without ``--docker`` or ``--remote``.
ja: ``destructive`` - ``--docker`` または ``--remote`` なしで ``--allow-destructive`` を実行する必要があります。

en: ``hidden`` - Target is ignored. Usable as a dependency. Automatic for ``setup_`` and ``prepare_`` prefixed targets.
ja: ``hidden`` - ターゲットは無視されます。依存関係として使用できます。プレフィックス ``setup_`` および ``prepare_`` が付けられたターゲットに対する自動化。

en: Tests which fail sometimes should be marked with the ``unstable`` alias until the instability has been fixed. These tests will continue to run for pull requests which modify the test or the module under test.
ja: 時々失敗するテストは、不安定性が修正されるまで、``unstable`` エイリアスでマークする必要があります。これらのテストは、テストまたはテスト対象のモジュールを変更するプル要求に対して引き続き実行します。

en: This avoids unnecessary test failures for other pull requests, as well as tests on merge runs and nightly CI jobs.
ja: これにより、他のプル要求に対する不要なテストの失敗や、マージの実行および毎夜の CI ジョブのテストも回避されます。

en: There are two ways to run unstable tests manually:
ja: 不安定なテストを手動で実行する方法は 2 つあります。

en: Use the ``--allow-unstable`` option for ``ansible-test``
ja: ``ansible-test`` には ``--allow-unstable`` オプションを使用します。

en: Prefix the test name with ``unstable/`` when passing it to ``ansible-test``.
ja: それを ``ansible-test`` に渡す場合は、テスト名の前にプレフィックス ``unstable/`` を付けます。

en: Tests will be marked as unstable by a member of the Ansible Core Team. GitHub issues_ will be created to track each unstable test.
ja: テストは、Ansible Core Team のメンバーによって Unstable と表示されます。GitHub 問題_ が作成され、不安定な各テストを追跡します。

en: Tests which always fail should be marked with the ``disabled`` alias until they can be fixed.
ja: 常に失敗するテストでは、修正されるまで、``disabled`` なエイリアスでマークされる必要があります。

en: Disabled tests are automatically skipped.
ja: 無効にされたテストは自動的にスキップされます。

en: There are two ways to run disabled tests manually:
ja: 無効にされたテストを手動で実行する方法は 2 つあります。

en: Use the ``--allow-disabled`` option for ``ansible-test``
ja: ``ansible-test`` には ``--allow-disabled`` オプションを使用します。

en: Prefix the test name with ``disabled/`` when passing it to ``ansible-test``.
ja: それを ``ansible-test`` に渡す場合は、テスト名の前にプレフィックス ``disabled/`` を付けます。

en: Tests will be marked as disabled by a member of the Ansible Core Team. GitHub issues_ will be created to track each disabled test.
ja: テストは、Ansible Core Team のメンバーによって無効とマークされます。GitHub 問題_ が作成され、無効にされた各テストを追跡します。

en: Tests which cannot be run in CI should be marked with the ``unsupported`` alias. Most tests can be supported through the use of simulators and/or cloud plugins.
ja: CI で実行できないテストには、``unsupported`` エイリアスのマークを付ける必要があります。ほとんどのテストはシミュレーターやクラウドプラグインを使用することでサポートされます。

en: However, if that is not possible then marking a test as unsupported will prevent it from running in CI.
ja: ただし、テストが使用できない場合は、テストを unsupported と表示すると、CI でテストを実行できなくなります。

en: There are two ways to run unsupported tests manually:
ja: サポート対象外のテストを手動で実行する方法は 2 つあります。

en: Use the ``--allow-unsupported`` option for ``ansible-test``
ja: ``ansible-test`` には ``--allow-unsupported`` オプションを使用します。

en: Prefix the test name with ``unsupported/`` when passing it to ``ansible-test``.
ja: それを ``ansible-test`` に渡す場合は、テスト名の前にプレフィックス ``unsupported/`` を付けます。

en: Tests will be marked as unsupported by the contributor of the test.
ja: テストは、テストの貢献者によって unsupported とマークされます。

en: Cloud
ja: クラウド

en: Tests for cloud services and other modules that require access to external APIs usually require special support for testing in CI.
ja: 通常、外部 API へのアクセスを必要とするクラウドサービスおよびその他のモジュールのテストには、CI でのテストに特別なサポートが必要です。

en: These require an additional alias to indicate the required test plugin.
ja: これらには、必要なテストプラグインを指定するために追加のエイリアスが必要です。

en: Some of the available aliases are:
ja: 利用可能なエイリアスには、以下のものがあります。

en: Untested
ja: 未テスト

en: Every module and plugin should have integration tests, even if the tests cannot be run in CI.
ja: テストを CI で実行できない場合でも、すべてのモジュールおよびプラグインに統合テストが含まれる必要があります。

en: Issues
ja: 問題

en: Tests that are marked as unstable_ or disabled_ will have an issue created to track the status of the test. Each issue will be assigned to one of the following projects:
ja: unstable_ または disabled_ としてマークされているテストには、テストのステータスを追跡する問題が作成されます。それぞれの問題は以下のプロジェクトのいずれかに割り当てられます。

en: Questions
ja: ご質問はございますか。

en: For questions about integration tests reach out to @mattclay or @gundalow on GitHub or ``#ansible-devel`` on IRC.
ja: 統合テストに関する質問は、GitHub で @mattclay または @gundalow、または IRC で ``#ansible-devel`` にお問い合わせください。

en: line-endings
ja: 行末

en: All files must use ``\n`` for line endings instead of ``\r\n``.
ja: すべてのファイルは、``\r\n`` ではなく、行末に ``\n`` を使用する必要があります。

en: Most Python files should include the following boilerplate at the top of the file, right after the comment header and ``from __future__ import``:
ja: ほとんどの Python ファイルには、ファイルの上部、コメントヘッダーのおよび ``from __future__ import`` の直後に次の boilerplate を含める必要があります。

en: Python 2 has "new-style classes" and "old-style classes" whereas Python 3 only has new-style classes. Adding the ``__metaclass__ = type`` boilerplate makes every class defined in that file into a new-style class as well.
ja: Python 2 には「新スタイルのクラス」および「旧スタイルのクラス」が使用されますが、Python 3 には新スタイルのクラスのみが使用されます。また、``__metaclass__ = type`` boilerplate を追加すると、そのファイルで定義されているすべてのクラスが新しいスタイルのクラスになります。

en: no-assert
ja: assert は使用しない

en: Do not use ``assert`` in production Ansible python code. When running Python with optimizations, Python will remove ``assert`` statements, potentially allowing for unexpected behavior throughout the Ansible code base.
ja: 実稼働環境の Ansible Python コードで ``assert`` を使用しないでください。最適化で Python を実行すると、Python は ``assert`` ステートメントを削除すると、Ansible のコードベース全体で予期しない動作が可能になります。

en: Instead of using ``assert`` you should utilize simple ``if`` statements, that result in raising an exception. There is a new exception called ``AnsibleAssertionError`` that inherits from ``AnsibleError`` and ``AssertionError``. When possible, utilize a more specific exception than ``AnsibleAssertionError``.
ja: ``assert`` を使用する代わりに、簡単な ``if`` ステートメントを利用する必要があります。その結果、例外が発生します。``AnsibleError`` および ``AssertionError`` から継承する ``AnsibleAssertionError`` と呼ばれる新しい例外があります。可能であれば、``AnsibleAssertionError`` より具体的な例外を利用してください。

en: Modules will not have access to ``AnsibleAssertionError`` and should instead raise ``AssertionError``, a more specific exception, or just use ``module.fail_json`` at the failure point.
ja: モジュールは ``AnsibleAssertionError`` にアクセスできないため、代わりに ``AssertionError`` を高くすることはできません。あるいは、障害段階で ``module.fail_json`` を使用します。

en: no-basestring
ja: basestring は使用しない

en: Do not use ``isinstance(s, basestring)`` as basestring has been removed in Python3.  You can import ``string_types``, ``binary_type``, or ``text_type`` from ``ansible.module_utils.six`` and then use ``isinstance(s, string_types)`` or ``isinstance(s, (binary_type, text_type))`` instead.
ja: Python3 では ``isinstance(s, basestring)`` をベース文字列から削除しないでください。``string_types``、``binary_type``、または ``text_type`` を ``ansible.module_utils.six`` からインポートしてから、代わりに ``isinstance(s, string_types)`` または ``isinstance(s, (binary_type, text_type))`` を使用できます。

en: If this is part of code to convert a string to a particular type, ``ansible.module_utils.common.text.converters`` contains several functions that may be even better for you: ``to_text``, ``to_bytes``, and ``to_native``.
ja: これが文字列を特定の型に変換するコードの一部である場合、``ansible.module_utils.common.text.converters`` には、より良い関数がいくつか含まれています (``to_text``、``to_bytes``、および ``to_native``)。

en: no-dict-iteritems
ja: dict-iteritems は使用しない

en: The ``dict.iteritems`` method has been removed in Python 3. There are two recommended alternatives:
ja: この ``dict.iteritems`` メソッドは、Python 3 で削除されました。推奨される代替手段が 2 つあります。

en: no-dict-iterkeys
ja: dict-iterkeys は使用しない

en: The ``dict.iterkeys`` method has been removed in Python 3. Use the following instead:
ja: この ``dict.iterkeys`` メソッドは、Python 3 で削除されました。代わりに、以下を使用します。

en: no-dict-itervalues
ja: dict-itervalues は使用しない

en: The ``dict.itervalues`` method has been removed in Python 3. There are two recommended alternatives:
ja: この ``dict.itervalues`` メソッドは、Python 3 で削除されました。推奨される代替手段が 2 つあります。

en: no-get-exception
ja: get-exception は使用しない

en: We created a function, ``ansible.module_utils.pycompat24.get_exception`` to help retrieve exceptions in a manner compatible with Python 2.4 through Python 3.6.  We no longer support Python 2.4 and Python 2.5 so this is extraneous and we want to deprecate the function.  Porting code should look something like this:
ja: Python 2.4 ～ Python 3.6 と互換性がある方法で例外を取得するのに役立つ関数 ``ansible.module_utils.pycompat24.get_exception`` を作成しました。Python 2.4 および Python 2.5 はサポートされなくなったため、これは外部のものであり、この関数を廃止する必要があります。移植コードは、以下のようになります。

en: no-illegal-filenames
ja: 不正なファイル名は使用しない

en: Files and directories should not contain illegal characters or names so that Ansible can be checked out on any Operating System.
ja: ファイルとディレクトリーには、Ansible をどのオペレーティングシステムでもチェックアウトできるように、不正な文字や名前は使用しないでください。

en: Illegal Characters
ja: 不正な文字

en: The following characters are not allowed to be used in any part of the file or directory name;
ja: 以下の文字は、ファイルまたはディレクトリーの名前には使用できません。

en: Any characters whose integer representations are in the range from 0 through to 31 like ``\n``
ja: 整数表示が 0 から 31 までの文字 (例: ``\n``)

en: The following characters are not allowed to be used as the last character of a file or directory;
ja: 次の文字は、ファイルまたはディレクトリーの最後の文字には使用できません。

en: ``" "`` (just the space character)
ja: ``" "`` (空白文字のみ)

en: Illegal Names
ja: 不正な名前

en: The following names are not allowed to be used as the name of a file or directory excluding the extension;
ja: 以下の名前は、拡張子を除いてファイルまたはディレクトリーの名前として使用することはできません。

en: For example, the file ``folder/COM1``, ``folder/COM1.txt`` are illegal but ``folder/COM1-file`` or ``folder/COM1-file.txt`` is allowed.
ja: たとえば、``folder/COM1`` ファイルまたは ``folder/COM1.txt`` ファイルは許可されませんが、``folder/COM1-file`` ファイルまたは ``folder/COM1-file.txt`` ファイルは許可されます。

en: no-main-display
ja: main-display は使用しない

en: As of Ansible 2.8, ``Display`` should no longer be imported from ``__main__``.
ja: Ansible 2.8 以降、``Display`` は ``__main__`` からインポートしないようにしてください。

en: ``Display`` is now a singleton and should be utilized like the following::
ja: ``Display`` はシングルトンで、以下のように使用する必要があります。

en: There is no longer a need to attempt ``from __main__ import display`` inside a ``try/except`` block.
ja: ``try/except`` ブロック内で ``from __main__ import display`` を試行する必要がなくなりました。

en: no-smart-quotes
ja: スマート引用符は使用しない

en: Smart quotes (``”“‘’``) should not be used.  Use plain ascii quotes (``"'``) instead.
ja: スマート引用符 (``”“‘’``) は使用しないでください。代わりに、標準の ascii 引用符 (``"'``) を使用します。

en: no-tests-as-filters
ja: テストをフィルターとして使用しない

en: Using Ansible provided Jinja2 tests as filters will be removed in Ansible 2.9.
ja: Ansible が提供する Jinja2 テストをフィルターとして使用することは、Ansible 2.9 で削除されます。

en: Prior to Ansible 2.5, Jinja2 tests included within Ansible were most often used as filters. The large difference in use is that filters are referenced as ``variable | filter_name`` while Jinja2 tests are referenced as ``variable is test_name``.
ja: Ansible 2.5 以前は、Ansible に含まれる Jinja2 テストは、ほとんどがフィルターとして使用されていました。使用方法の大きな違いは、フィルターは ``variable | filter_name`` として参照されるのに対し、Jinja2 テストは ``variable is test_name`` として参照されることです。

en: Jinja2 tests are used for comparisons, whereas filters are used for data manipulation, and have different applications in Jinja2. This change is to help differentiate the concepts for a better understanding of Jinja2, and where each can be appropriately used.
ja: Jinja2 テストは比較のために使用され、フィルターはデータ操作のために使用され、Jinja2 でそれぞれ用途が異なります。この変更は、Jinja2 の理解を深めるために概念を区別し、それぞれを適切に使用できるようにするためのものです。

en: As of Ansible 2.5 using an Ansible provided Jinja2 test with filter syntax will display a deprecation error.
ja: Ansible 2.5 以降では、Ansible が提供する Jinja2 テストをフィルター構文で使用すると、非推奨エラーが表示されます。

en: In the future, Ansible may use the identifier ``_`` to internationalize its message strings.  To be ready for that, we need to make sure that there are no conflicting identifiers defined in the code base.
ja: 今後、Ansible は、識別子 ``_`` を使用して、メッセージ文字列を国際化することができます。そのためには、コードベースで定義されている識別子が競合しないようにする必要があります。

en: In common practice, ``_`` is frequently used as a dummy variable (a variable to receive a value from a function where the value is useless and never used). In Ansible, we're using the identifier ``dummy`` for this purpose instead.
ja: 一般的な慣行では、``_`` は、ダミー変数 (値が役に立たず、使用されない関数から値を受け取る変数) として頻繁に使用されます。Ansibleでは、代わりにこの目的のために識別子 ``dummy`` を使用しています。

en: Example of unfixed code:
ja: 未修正コードの例:

en: Example of fixed code:
ja: 修正したコードの例:

en: The use of :code:`from __future__ import unicode_literals` has been deemed an anti-pattern.  The problems with it are:
ja: :code:`from __future__ import unicode_literals` の使用はアンチパターンと見なされます。その問題は次のとおりです。

en: It makes it so one can't jump into the middle of a file and know whether a bare literal string is a byte string or text string.  The programmer has to first check the top of the file to see if the import is there.
ja: これにより、ファイルの途中にジャンプして、裸のリテラル文字列がバイト文字列なのかテキスト文字列なのかを知ることができなくなります。プログラマーは、最初にファイルの先頭をチェックして、インポートが存在するかどうかを確認する必要があります。

en: It removes the ability to define native strings (a string which should be a byte string on python2 and a text string on python3) via a string literal.
ja: これにより、文字列リテラルを介してネイティブ文字列 (python2 ではバイト文字列、python3 ではテキスト文字列である必要がある文字列) を定義する機能が削除されます。

en: It makes for more context switching.  A programmer could be reading one file which has `unicode_literals` and know that bare string literals are text strings but then switch to another file (perhaps tracing program execution into a third party library) and have to switch their understanding of what bare string literals are.
ja: そのため、コンテキストの切り替えが多くなります。プログラマーは、`unicode_literals` を含むあるファイルを読み込んでいて、裸の文字列リテラルがテキスト文字列であることを知っていますが、その後、別のファイル (おそらくサードパーティーのライブラリーへのプログラム実行の追跡) に切り替えて、裸の文字列リテラルが何であるかの理解を切り替えなければなりません。

en: no-unwanted-files
ja: 不要なファイルは使用しない

en: Specific file types are allowed in certain directories:
ja: 特定のファイルタイプは、特定のディレクトリーで許可されます。

en: ``lib`` - All content must reside in the ``lib/ansible`` directory.
ja: ``lib`` - すべてのコンテンツは ``lib/ansible`` ディレクトリーに置く必要があります。

en: ``lib/ansible`` - Only source code with one of the following extensions is allowed:
ja: ``lib/ansible`` - 以下の拡張機能のいずれかを持つソースコードのみが許可されます。

en: no-wildcard-import
ja: ワイルドカードの import は使用しない

en: Using :code:`import *` is a bad habit which pollutes your namespace, hinders debugging, and interferes with static analysis of code.  For those reasons, we do want to limit the use of :code:`import *` in the ansible code.  Change our code to import the specific names that you need instead.
ja: :code:`import *` を使用することは、名前空間を汚染し、デバッグを妨げ、コードの静的分析を妨げる悪い習慣です。これらの理由から、Ansible コードで :code:`import *` の使用を制限します。代わりに、必要な特定の名前をインポートするようにコードを変更してください。

en: Examples of unfixed code:
ja: 未修正コードの例:

en: Examples of fixed code:
ja: 修正されたコードの例:

en: obsolete-files
ja: 陳腐化したファイル

en: Directories in the Ansible source tree are sometimes made obsolete. Files should not exist in these directories. The new location (if any) is dependent on which directory has been made obsolete.
ja: Ansible ソースツリー内のディレクトリーは廃止されることがあります。ファイルは、このディレクトリーに存在すべきではありません。新しい場所が存在する場合は、どのディレクトリーが廃止されたかに依存しています。

en: Below are some of the obsolete directories and their new locations:
ja: 古いディレクトリーとその新しい場所を以下に示します。

en: All of ``test/runner/`` is now under ``test/lib/ansible_test/`` instead. The organization of files in the new directory has changed.
ja: すべての ``test/runner/`` は、現在、代わりに ``test/lib/ansible_test/`` にあります。新しいディレクトリーのファイルの編成が変更になりました。

en: Most subdirectories of ``test/sanity/`` (with some exceptions) are now under ``test/lib/ansible_test/_data/sanity/`` instead.
ja: ``test/sanity/`` (例外あり) のサブディレクトリーのほとんどは、代わりに ``test/lib/ansible_test/_data/sanity/`` の下にあります。

en: This error occurs most frequently for open pull requests which add or modify files in directories which are now obsolete. Make sure the branch you are working from is current so that changes can be made in the correct location.
ja: このエラーは、現在古くなったディレクトリーのファイルを追加または変更するオープンなプル要求に対して最も頻繁に発生します。正しい場所で変更できるように、作業しているブランチが現在の状態であることを確認します。

en: Verifies that the combination of ``MANIFEST.in`` and ``package_data`` from ``setup.py`` properly installs data files from within ``lib/ansible``
ja: ``setup.py`` から ``MANIFEST.in`` と ``package_data`` を組み合わせて、``lib/ansible`` 内からデータファイルが適切にインストールされていることを確認します。

en: Python static analysis for PEP 8 style guideline compliance.
ja: PEP 8 スタイルのガイドラインコンプライアンスに対する Python 静的分析です。

en: See :ref:`testing_pep8` for more information.
ja: 詳細は、「:ref:`testing_pep8`」を参照してください。

en: PowerShell static analysis for common programming errors using `PSScriptAnalyzer <https://github.com/PowerShell/PSScriptAnalyzer/>`_.
ja: `PSScriptAnalyzer <https://github.com/PowerShell/PSScriptAnalyzer/>`_ を使用した一般的なプログラミングエラーに関する PowerShell の静的な分析です。

en: Python static analysis for common programming errors.
ja: 一般的なプログラミングエラーに対する Python の静的分析です。

en: A more strict set of rules applied to ``ansible-test``.
ja: ``ansible-test`` に適用されるより厳密なルールセット

en: Release names
ja: リリース名

en: Verifies that the most recent release name has been added to ``./github/RELEASE_NAMES.yml``
ja: 最新のリリース名が ``./github/RELEASE_NAMES.yml`` に追加されたことを確認します。

en: Use ``open_url`` from ``module_utils`` instead of ``urlopen``.
ja: ``urlopen`` の代わりに ``module_utils`` から ``open_url`` を使用します。

en: Use only one of ``default`` or ``required`` with ``FieldAttribute``.
ja: ``default`` または ``required`` の 1 つのみを ``FieldAttribute`` で使用します。

en: Check reStructuredText files for syntax and formatting issues.
ja: 構文およびフォーマットに関する問題は、eStructuredTex ファイルを確認してください。

en: Validates the schema for:
ja: スキーマを検証します。

en: ansible-core's ``lib/ansible/config/ansible_builtin_runtime.yml``
ja: ansible-core の ``lib/ansible/config/ansible_builtin_runtime.yml``

en: collection's ``meta/runtime.yml``
ja: コレクションの ``meta/runtime.yml``

en: Documentation for each ``ansible-test sanity`` test is required.
ja: 各 ``ansible-test sanity`` テスト用のドキュメントが必要です。

en: Most executable files should only use one of the following shebangs:
ja: 実行ファイルのほとんどは、以下のいずれかの shebang のみを使用する必要があります。

en: NOTE: For ``#!/bin/bash``, any of the options ``eux`` may also be used, such as ``#!/bin/bash -eux``.
ja: 注記: ``#!/bin/bash`` の場合は、いずれのオプションの ``eux`` も使用できます (``#!/bin/bash -eux`` など)。

en: This does not apply to Ansible modules, which should not be executable and must always use ``#!/usr/bin/python``.
ja: これは Ansible モジュールには適用されません。これは実行可能ではなく、``#!/usr/bin/python`` を常に使用する必要があります。

en: Some exceptions are permitted. Ask if you have questions.
ja: 一部の例外が許可されます。ご質問がある場合はお問い合わせください。

en: Static code analysis for shell scripts using the excellent `shellcheck <https://www.shellcheck.net/>`_ tool.
ja: 優れた `shellcheck <https://www.shellcheck.net/>`_ ツールを使用してシェルスクリプトの静的コード分析。

en: Symbolic links are only permitted for files that exist to ensure proper tarball generation during a release.
ja: シンボリックリンクは、リリース中に適切な tarball 生成を保証するファイルにのみ許可されます。

en: If other types of symlinks are needed for tests they must be created as part of the test.
ja: テストに他のシンボリックリンクが必要な場合は、テストの一部として作成する必要があります。

en: Constraints for test requirements should be in ``test/lib/ansible_test/_data/requirements/constraints.txt``.
ja: テスト要件の制約は ``test/lib/ansible_test/_data/requirements/constraints.txt`` に保存されている必要があります。

en: Check whether any of our known bundled code needs to be updated for a new upstream release.
ja: 既知のバンドルされたコードが新しいアップストリームリリース用に更新する必要があるかどうかを確認します。

en: This test can error in the following ways:
ja: このテストは以下の方法でエラーが発生する可能性があります。

en: The bundled code is out of date with regard to the latest release on pypi.  Update the code to the new version and update the version in _BUNDLED_METADATA to solve this.
ja: バンドルされたコードは pypi の最新リリースに関して古くなっています。コードを新しいバージョンに更新し、_BUNDLED_METADATA でバージョンを更新してこれを解決します。

en: The code is lacking a _BUNDLED_METADATA variable.  This typically happens when a bundled version is updated and we forget to add a _BUNDLED_METADATA variable to the updated file.  Once that is added, this error should go away.
ja: このコードには _BUNDLED_METADATA 変数がありません。これは通常、バンドルバージョンが更新され、更新されたファイルに _BUNDLED_METADATA 変数を追加し忘れた場合に発生します。それが追加されると、このエラーはなくなるはずです。

en: A file has a _BUNDLED_METADATA variable but the file isn't specified in :file:`test/sanity/code-smell/update-bundled.py`.  This typically happens when a new bundled library is added.  Add the file to the `get_bundled_libs()` function in the `update-bundled.py` test script to solve this error.
ja: ファイルには、_BUNDLED_METADATA 変数がありますが、そのファイルは :file:`test/sanity/code-smell/update-bundled.py` で指定されていません。これは通常、新しいバンドルライブラリーが追加されたときに発生します。このエラーを解決するために、`update-bundled.py` テストスクリプトの `get_bundled_libs()` 関数にファイルを追加します。

en: _BUNDLED_METADATA has the following fields:
ja: _BUNDLED_METADATA には以下のフィールドがあります。

en: Name of the bundled package on pypi
ja: pypi でバンドルされたパッケージの名前

en: Version of the package that we are including here
ja: ここに含めるパッケージのバージョン

en: Optional PEP440 specifier for the version range that we are bundling. Currently, the only valid use of this is to follow a version that is compatible with the Python stdlib when newer versions of the pypi package implement a new API.
ja: バンドルするバージョン範囲の任意の PEP440 指定子。現在、これの唯一の有効な使用法は、新しいバージョンの pypi パッケージが新しい API を実装するときに、Python stdlib と互換性のあるバージョンに従うことです。

en: The AnsibleModule argument_spec knows of several types beyond the standard python types.  One of these is ``path``.  When used, type ``path`` ensures that an argument is a string and expands any shell variables and tilde characters.
ja: AnsibleModule の argument_spec は、標準の python タイプ以外の複数のタイプを認識します。これらのいずれかが ``path`` になります。使用すると、``path`` と入力して、引数が文字列で、シェル変数とチルダ文字を拡張するようにします。

en: This test looks for use of :func:`os.path.expanduser <python:os.path.expanduser>` in modules.  When found, it tells the user to replace it with ``type='path'`` in the module's argument_spec or list it as a false positive in the test.
ja: このテストでは、モジュールで :func:`os.path.expanduser <python:os.path.expanduser>` の使用を探します。見つかった場合は、モジュールの argument_spec で ``type='path'`` に置き換えるか、テストで誤検出として一覧に挙げられます。

en: Use ``six`` from ``module_utils`` instead of ``six``.
ja: ``six`` の代わりに ``module_utils`` から ``six`` を使用します。

en: Analyze modules for common issues in code and documentation.
ja: コードおよびドキュメントの一般的な問題についてモジュールを分析します。

en: See :ref:`testing_validate-modules` for more information.
ja: 詳細は、「:ref:`testing_validate-modules`」を参照してください。

en: Check YAML files for syntax and formatting issues.
ja: YAML ファイルにおける構文およびフォーマットの問題を確認します。

en: Compile Tests
ja: コンパイルテスト

en: Overview
ja: 概要

en: Compile tests check source files for valid syntax on all supported python versions:
ja: コンパイルテストでは、サポートされているすべての python バージョンで、ソースファイルの構文が有効かどうかを確認します。

en: 2.4 (Ansible 2.3 only)
ja: 2.4 (Ansible 2.3 のみ)

en: NOTE: In Ansible 2.4 and earlier the compile test was provided by a dedicated sub-command ``ansible-test compile`` instead of a sanity test using ``ansible-test sanity --test compile``.
ja: 注記: Ansible 2.4 以前では、``ansible-test sanity --test compile`` を使用する健全性テストの代わりに、コンパイルテストが専用のサブコマンド ``ansible-test compile`` によって提供されていました。

en: Running compile tests locally
ja: ローカルでのコンパイルテストの実行

en: Compile tests can be run across the whole code base by doing:
ja: コンパイルテストを実行するには、次のように、コードベース全体でテストを実行できます。

en: Against a single file by doing:
ja: 1 つのファイルに対して以下を行います。

en: Or against a specific Python version by doing:
ja: または、特定の Python バージョンに対して以下を実行します。

en: For advanced usage see the help:
ja: 高度な使用方法は、ヘルプを参照してください。

en: Installing dependencies
ja: 依存関係のインストール

en: ``ansible-test`` has a number of dependencies , for ``compile`` tests we suggest running the tests with ``--local``, which is the default
ja: ``ansible-test`` にはいくつかの依存関係があります。``compile`` テストでは、デフォルトである ``--local`` を使用してテストを実行することが推奨されます。

en: The dependencies can be installed using the ``--requirements`` argument. For example:
ja: 依存関係は、``--requirements`` 引数を使用してインストールできます。以下に例を示します。

en: The full list of requirements can be found at `test/lib/ansible_test/_data/requirements <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements>`_. Requirements files are named after their respective commands. See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ applicable to all commands.
ja: 要件の一覧は `test/lib/ansible_test/_data/requirements <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements>`_ に記載されています。要件ファイルには、各コマンドにちなんで名前が付けられています。全コマンドに適用される `制約 <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ も参照してください。

en: Extending compile tests
ja: コンパイルテストの拡張

en: If you believe changes are needed to the compile tests please add a comment on the `Testing Working Group Agenda <https://github.com/ansible/community/blob/master/meetings/README.md>`_ so it can be discussed.
ja: コンパイルテストに変更が必要な場合は、`ワーキンググループのテストの議題 <https://github.com/ansible/community/blob/master/meetings/README.md>`_ にコメントを追加してください。その内容について話し合うことができます。

en: Before you submit a module for inclusion in the main Ansible repo, you must test your module documentation for correct HTML rendering and to ensure that the argspec matches the documentation in your Python file. The community pages offer more information on :ref:`testing reStructuredText documentation <testing_documentation_locally>`.
ja: メインの Ansible リポジトリーに組み込むモジュールを送信する前に、正しい HTML レンダリングついてモジュールドキュメントをテストする必要があります。また、argspec が Python ファイルのドキュメントと一致することを確認する必要があります。コミュニティーページでは、「:ref:`reStructuredText ドキュメントのテスト <testing_documentation_locally>`」の詳細が提供されています。

en: To check the HTML output of your module documentation:
ja: モジュールドキュメントの HTML 出力を確認するには、次のコマンドを実行します。

en: Ensure working :ref:`development environment <environment_setup>`.
ja: :ref:`開発環境 <environment_setup>` が稼働していることを確認します。

en: Install required Python packages (drop '--user' in venv/virtualenv):
ja: 必要な Python パッケージをインストールします (venv/virtualenv に「--user」をドロップします)。

en: Ensure your module is in the correct directory: ``lib/ansible/modules/$CATEGORY/mymodule.py``.
ja: モジュールが正しいディレクトリー (``lib/ansible/modules/$CATEGORY/mymodule.py``) にあることを確認します。

en: Build HTML from your module documentation: ``MODULES=mymodule make webdocs``.
ja: モジュールドキュメント ``MODULES=mymodule make webdocs`` から HTML を構築します。

en: To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=mymodule,mymodule2 make webdocs``.
ja: 複数のモジュールの HTML ドキュメントを作成するには、モジュール名のコンマ区切りリストを使用します (``MODULES=mymodule,mymodule2 make webdocs``)。

en: View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html``.
ja: ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html`` で HTML ページを表示します。

en: To ensure that your module documentation matches your ``argument_spec``:
ja: モジュールのドキュメントが ``argument_spec`` と適合するようにするには、以下を行います。

en: run the ``validate-modules`` test::
ja: ``validate-modules`` テストを実行します。

en: ``httptester`` is a docker container used to host certain resources required by :ref:`testing_integration`. This is to avoid CI tests requiring external resources (such as git or package repos) which, if temporarily unavailable, would cause tests to fail.
ja: ``httptester`` は、:ref:`testing_integration` で必要な特定のリソースをホストするのに使用される docker コンテナーです。これにより、(git やパッケージリポジトリーなどの) 外部リソースを必要とする CI テストが回避され、一時的に利用できなくなるとテストが失敗します。

en: HTTP Testing endpoint which provides the following capabilities:
ja: 以下の機能を提供する HTTP テストエンドポイントです。

en: Negotiate Authentication
ja: 認証のネゴシエート

en: Source files can be found in the `http-test-container <https://github.com/ansible/http-test-container>`_ repository.
ja: ソースファイルは `http-test-container <https://github.com/ansible/http-test-container>`_ リポジトリーにあります。

en: Extending httptester
ja: httptester の拡張

en: If you have sometime to improve ``httptester`` please add a comment on the `Testing Working Group Agenda <https://github.com/ansible/community/blob/master/meetings/README.md>`_ to avoid duplicated effort.
ja: ``httptester`` を改善するタイミングがある場合は、重複作業を回避するために、`ワーキンググループのテストの議題 <https://github.com/ansible/community/blob/master/meetings/README.md>`_ にコメントを追加します。

en: The Ansible integration Test system.
ja: Ansible 統合テストシステム。

en: Tests for playbooks, by playbooks.
ja: Playbook による Playbook のテスト

en: Some tests may require credentials.  Credentials may be specified with `credentials.yml`.
ja: テストによっては認証情報が必要になる場合があります。認証情報は `credentials.yml` で指定できます。

en: Some tests may require root.
ja: テストによっては root が必要になる場合があります。

en: Quick Start
ja: クイックスタート

en: It is highly recommended that you install and activate the ``argcomplete`` python package. It provides tab completion in ``bash`` for the ``ansible-test`` test runner.
ja: python パッケージ ``argcomplete`` をインストールし、アクティベートすることが強く推奨されます。これにより、テストランナー ``ansible-test`` に ``bash`` のタブ補完が提供されます。

en: Configuration
ja: 設定

en: ansible-test command
ja: ansible-test コマンド

en: The example below assumes ``bin/`` is in your ``$PATH``. An easy way to achieve that is to initialize your environment with the ``env-setup`` command::
ja: 以下の例では、``bin/`` が ``$PATH`` であることを前提としています。これは、``env-setup`` コマンドで環境を初期化する簡単な方法になります。

en: You can also call ``ansible-test`` with the full path::
ja: 完全パスで ``ansible-test`` を呼び出すこともできます。

en: Making your own version of ``integration_config.yml`` can allow for setting some tunable parameters to help run the tests better in your environment.  Some tests (for example, cloud tests) will only run when access credentials are provided.  For more information about supported credentials, refer to the various ``cloud-config-*.template`` files in the ``test/integration/`` directory.
ja: 自身で作成した ``integration_config.yml`` があると、一部の調整可能なパラメーターを設定して、環境により適切にテストを実行できます。一部のテスト (クラウドテストなど) は、アクセス認証情報が提供されている場合にのみ実行されます。サポート対象の認証情報の詳細は、``test/integration/`` ディレクトリーでさまざまな ``cloud-config-*.template`` ファイルを参照してください。

en: Some tests assume things like hg, svn, and git are installed, and in path.  Some tests (such as those for Amazon Web Services) need separate definitions, which will be covered later in this document.
ja: 一部のテストでは、hg、svn、git などがインストールされ、パスにあることを前提としています。一部のテスト (Amazon Web Services のテストなど) には個別の定義が必要です。これについては、このドキュメントの後半で説明します。

en: (Complete list pending)
ja: (完全はリストは後日追加されます)

en: Non-destructive Tests
ja: 非破壊テスト

en: These tests will modify files in subdirectories, but will not do things that install or remove packages or things outside of those test subdirectories.  They will also not reconfigure or bounce system services.
ja: これらのテストはサブディレクトリー内のファイルを修正しますが、パッケージやテストのサブディレクトリー以外にあるものをインストールしたり削除したりするようなことはしません。また、システムサービスの再設定やバウンスも行いません。

en: Running integration tests within Docker
ja: Docker 内での統合テストの実行

en: To protect your system from any potential changes caused by integration tests, and to ensure a sensible set of dependencies are available we recommend that you always run integration tests with the ``--docker`` option, for example ``--docker centos8``. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for options (the ``default`` image is used for sanity and unit tests, as well as for platform independent integration tests such as those for cloud modules).
ja: 統合テストによる潜在的な変更からシステムを守り、適切な依存関係セットが利用可能になるようにするには、常に ``--docker`` オプションをつけて統合テストを実行することが推奨されます (``--docker centos8`` など)。オプションについては、「`サポート対象外の docker イメージの一覧 <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_」を参照してください (``default``イメージは、健全性テストとユニットテスト、およびクラウドモジュールなどのプラットフォームに依存しない統合テストに使用されます)。

en: Avoiding pulling new Docker images
ja: 新規 Docker イメージのプルの回避

en: Use the ``--docker-no-pull`` option to avoid pulling the latest container image. This is required when using custom local images that are not available for download.
ja: 最新のコンテナーイメージをプルしないようにするには、``--docker-no-pull`` オプションを使用します。これは、ダウンロードに利用できないカスタムのローカルイメージを使用する場合に必要です。

en: Run as follows for all POSIX platform tests executed by our CI system in a fedora32 docker container::
ja: fedora32 docker コンテナーで CI システムによって実行されるすべての POSIX プラットフォームテストに対して次のように実行します。

en: You can target a specific tests as well, such as for individual modules::
ja: 個々のモジュールなど、特定のテストを対象とすることもできます。

en: You can use the ``-v`` option to make the output more verbose::
ja: ``-v`` オプションを使用すると、出力をさらに詳細にすることができます。

en: Use the following command to list all the available targets::
ja: 利用可能なターゲットの一覧を表示するには、以下のコマンドを実行します。

en: Bash users
ja: Bash ユーザー

en: If you use ``bash`` with ``argcomplete``, obtain a full list by doing: ``ansible-test integration <tab><tab>``
ja: ``bash`` を ``argcomplete`` とともに使用する場合は、``ansible-test integration <tab><tab>`` を実行して完全な一覧を取得します。

en: Destructive Tests
ja: 破壊テスト

en: These tests are allowed to install and remove some trivial packages.  You will likely want to devote these to a virtual environment, such as Docker.  They won't reformat your filesystem::
ja: これらのテストでは、いくつかの簡単なパッケージをインストールおよび削除できます。これらを Docker などの仮想環境専用にすることが推奨されます。これらは、ファイルシステムを再フォーマットしません。

en: Windows Tests
ja: Windows テスト

en: These tests exercise the ``winrm`` connection plugin and Windows modules.  You'll need to define an inventory with a remote Windows 2008 or 2012 Server to use for testing, and enable PowerShell Remoting to continue.
ja: これらのテストは、``winrm`` 接続プラグインと Windows モジュールに従います。テストに使用するリモート Windows 2008 Server または 2012 Server を持つインベントリーを定義し、PowerShell Remoting を継続できるようにする必要があります。

en: Running these tests may result in changes to your Windows host, so don't run them against a production/critical Windows environment.
ja: これらのテストを実行すると、Windows ホストが変更になる可能性があるため、実稼働環境や重要な Windows 環境では実行しないでください。

en: Enable PowerShell Remoting (run on the Windows host via Remote Desktop)::
ja: PowerShell Remoting を有効にします (リモートデスクトップを介して Windows ホストで実行します)。

en: Define Windows inventory::
ja: Windows インベントリーを定義します。

en: Run the Windows tests executed by our CI system::
ja: CI システムで実行する Windows テストを実行します。

en: Tests in Docker containers
ja: Docker コンテナーでのテスト

en: If you have a Linux system with Docker installed, running integration tests using the same Docker containers used by the Ansible continuous integration (CI) system is recommended.
ja: Docker がインストールされた Linux システムをお持ちの場合は、Ansible の継続的統合 (CI) システムで使用されているものと同じ Docker コンテナーを使用して統合テストを実行することが推奨されます。

en: Docker on non-Linux
ja: Linux 以外の Docker

en: Using Docker Engine to run Docker on a non-Linux host (such as macOS) is not recommended. Some tests may fail, depending on the image used for testing. Using the ``--docker-privileged`` option when running ``integration`` (not ``network-integration`` or ``windows-integration``) may resolve the issue.
ja: Docker Engine を使用して (macOS などの) Linux 以外のホストで Docker を実行することは推奨されません。テストに使用されるイメージによっては、一部のテストが失敗する可能性があります。(``network-integration`` または ``windows-integration``ではなく) ``integration`` の実行時に ``--docker-privileged`` オプションを使用すると問題が解決する可能性があります。

en: Running Integration Tests
ja: 統合テストの実行

en: To run all CI integration test targets for POSIX platforms in a Ubuntu 18.04 container::
ja: Ubuntu 18.04 コンテナー内の POSIX プラットフォームに CI 統合テストターゲットすべてを実行するには、次のコマンドを実行します。

en: You can also run specific tests or select a different Linux distribution. For example, to run tests for the ``ping`` module on a Ubuntu 18.04 container::
ja: 特定のテストを実行することも、別の Linux ディストリビューションを選択することもできます。たとえば、Ubuntu 18.04 コンテナーで ``ping`` モジュールのテストを実行するには、次を実行します。

en: Container Images
ja: コンテナーイメージ

en: Most container images are for testing with Python 2:
ja: ほとんどのコンテナーイメージは、Python 2 でテストするためのものです。

en: To test with Python 3 use the following images:
ja: Python 3 でテストするには、以下のイメージを使用します。

en: Legacy Cloud Tests
ja: レガシーのクラウドテスト

en: Some of the cloud tests run as normal integration tests, and others run as legacy tests; see the :ref:`testing_integration_legacy` page for more information.
ja: 一部のクラウドテストは通常の統合テストとして実行し、その他はレガシーテストとして実行します。詳細は、「:ref:`testing_integration_legacy`」のドキュメントを参照してください。

en: Other configuration for Cloud Tests
ja: クラウドテストのその他の設定

en: In order to run some tests, you must provide access credentials in a file named ``cloud-config-aws.yml`` or ``cloud-config-cs.ini`` in the test/integration directory. Corresponding .template files are available for for syntax help.  The newer AWS tests now use the file test/integration/cloud-config-aws.yml
ja: test/integration ディレクトリーにある ``cloud-config-aws.yml`` または ``cloud-config-cs.ini`` という名前のファイルにあるアクセス認証情報を指定する必要があります。構文ヘルプでは、対応する .template ファイルを利用できます。新しい AWS テストでは、test/integration/cloud-config-aws.yml ファイルが使用されるようになりました。

en: IAM policies for AWS
ja: AWS の IAM ポリシー

en: Ansible needs fairly wide ranging powers to run the tests in an AWS account.  This rights can be provided to a dedicated user. These need to be configured before running the test.
ja: Ansible は、AWS アカウントでテストを実行するために非常に幅広い権限が必要になります。この権限は専用のユーザーに提供できます。これらの権限は、テストを実行する前に設定する必要があります。

en: The GitHub repository `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator/>`_ contains two sets of policies used for all existing AWS module integratoin tests. The `hacking/aws_config/setup_iam.yml` playbook can be used to setup two groups:
ja: GitHub リポジトリー `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator/>`_ には、既存の AWS モジュールの統合テストに使用するポリシーのセットが 2 つ含まれます。Playbook `hacking/aws_config/setup_iam.yml` を使用すると、2 つのグループを設定できます。

en: `ansible-integration-ci` will have the policies applied necessary to run any integration tests not marked as `unsupported` and are designed to mirror those used by Ansible's CI.
ja: `ansible-integration-ci` は、統合テストの実行に必要となるポリシーを適用すると共に、`unsupported` と識別されず、Ansible の CI で使用されるミラーリング用に設計されています。

en: `ansible-integration-unsupported` will have the additional policies applied necessary to run the integration tests marked as `unsupported` including tests for managing IAM roles, users and groups.
ja: `ansible-integration-unsupported` は、IAM ロール、ユーザー、およびグループを管理するためのテストを含む `unsupported` とマークされた統合テストの実行に必要な追加のポリシーが適用されます。

en: Once the groups have been created, you'll need to create a user and make the user a member of these groups. The policies are designed to minimize the rights of that user.  Please note that while this policy does limit the user to one region, this does not fully restrict the user (primarily due to the limitations of the Amazon ARN notation). The user will still have wide privileges for viewing account definitions, and will also able to manage some resources that are not related to testing (for example, AWS lambdas with different names).  Tests should not be run in a primary production account in any case.
ja: グループが作成されたら、ユーザーを作成して、そのユーザーをこれらのグループのメンバーにする必要があります。ポリシーは、そのユーザーの権利を最小限にするためのものです。このポリシーでは、ユーザーを 1 つの地域に限定していますが、これはユーザーを完全には制限していないことに注意してください (主に Amazon ARN 表記の制限によるものです)。このユーザーは、アカウント定義を閲覧するための広い権限を持っており、テストに関係のないいくつかのリソース (たとえば、異なる名前の AWS ラムダ) を管理することもできます。どのような場合でも、テストを実稼働環境用のプライマリーアカウントで実行すべきではありません。

en: Other Definitions required
ja: その他に必要な定義

en: Apart from installing the policy and giving it to the user identity running the tests, a lambda role `ansible_integration_tests` has to be created which has lambda basic execution privileges.
ja: ポリシーをインストールして、テストを実行しているユーザ ID にそれを付与することとは別に、ラムダロール `ansible_integration_tests` を作成する必要があります。これは、ラムダの基本的な実行権限を持ちます。

en: Network Tests
ja: ネットワークテスト

en: For guidance on writing network test see :ref:`testing_resource_modules`.
ja: ネットワークテストの書き込みに関する情報は、「:ref:`testing_resource_modules`」を参照してください。

en: Where to find out more
ja: その他の詳細情報

en: If you'd like to know more about the plans for improving testing Ansible, join the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
ja: Ansible テストを改善する詳細な計画を確認したい場合は、`テストのワーキンググループ <https://github.com/ansible/community/blob/master/meetings/README.md>`_ にご参加ください。

en: Testing using the Legacy Integration system
ja: レガシー統合システムを使用したテスト

en: This page details how to run the integration tests that haven't been ported to the new ``ansible-test`` framework.
ja: このページでは、新しい ``ansible-test`` フレームワークに移植されていない統合テストの実行方法を説明します。

en: The following areas are still tested using the legacy ``make tests`` command:
ja: 以下のエリアは、レガシーの ``make tests`` コマンドを使用してテストされます。

en: amazon (some)
ja: amazon (一部)

en: Over time the above list will be reduced as tests are ported to the ``ansible-test`` framework.
ja: テストが ``ansible-test`` フレームワークに移植されると、上記のリストは徐々に少なくなっていきます。

en: Running Cloud Tests
ja: クラウドテストの実行

en: Cloud tests exercise capabilities of cloud modules (for example, ec2_key).  These are not 'tests run in the cloud' so much as tests that leverage the cloud modules and are organized by cloud provider.
ja: クラウドテストは、クラウドモジュール (ec2_key など) の機能を実行します。これらは、「クラウドで実行されるテスト」ではなく、クラウドモジュールを活用し、クラウドプロバイダーによって編成されたテストです。

en: Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, and so on) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html>`_ for information on creating a profile.
ja: AWS テストによっては、環境変数を使用するものもあります。AWS 環境変数 (``AWS_DEFAULT_PROFILE``、``AWS_SECRET_ACCESS_KEY`` など) の設定を解除するか、環境変数が ``credentials.yml`` で提供される認証情報と一致することを確認して、予想されるアカウントの完全な機能に一貫性のあるテストが実行されるようにすることが推奨されます。プロファイルの作成に関する情報は、`AWS CLI ドキュメント <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html>`_ を参照してください。

en: Subsets of tests may be run by ``#commenting`` out unnecessary roles in the appropriate playbook, such as ``test/integration/amazon.yml``.
ja: テストのサブセットは、適切な Playbook の 不要なロールを ``#commenting`` でコメントアウトすることで実行できます (例: ``test/integration/amazon.yml``)。

en: In order to run cloud tests, you must provide access credentials in a file named ``credentials.yml``. A sample credentials file named ``credentials.template`` is available for syntax help.
ja: クラウドテストを実行するには、``credentials.yml`` という名前のファイルでアクセス認証情報を指定する必要があります。構文ヘルプには、``credentials.template`` と名前の付いたサンプル認証情報ファイルを利用できます。

en: Provide cloud credentials::
ja: クラウド認証を提供します。

en: Other configuration
ja: その他の設定

en: In order to run some tests, you must provide access credentials in a file named ``credentials.yml``. A sample credentials file named ``credentials.template`` is available for syntax help.
ja: いくつかのテストを実行するには、``credentials.yml`` という名前のファイルでアクセス認証情報を指定する必要があります。構文ヘルプには、``credentials.template`` と名前の付いたサンプル認証情報ファイルを利用できます。

en: In order to run the tests in an AWS account ansible needs fairly wide ranging powers which can be provided to a dedicated user or temporary credentials using a specific policy configured in the AWS account.
ja: AWS アカウントでテストを実行するには、Ansible に、AWS アカウントで設定された特定のポリシーを使用して、専用のユーザや一時的な認証情報に提供できる、かなり広範囲の権限が必要となります。

en: The testing-iam-policy.json.j2 file contains a policy which can be given to the user running the tests to give close to minimum rights required to run the tests.  Please note that this does not fully restrict the user; The user has wide privileges for viewing account definitions and is also able to manage some resources that are not related to testing (for example, AWS lambdas with different names) primarily due to the limitations of the Amazon ARN notation.  At the very least the policy limits the user to one region, however tests should not be run in a primary production account in any case.
ja: testing-iam-policy.json.j2 ファイルには、テストを実行するユーザーに付与するポリシーが含まれており、テストの実行に必要な最低限の権限に近いものを付与することができます。なお、これは完全な制限ではないため注意してください。このユーザーは、アカウント定義を閲覧する幅広い権限を持ち、主に Amazon ARN 表記の制限により、テストに関係のない一部のリソース (たとえば、異なる名前の AWS ラムダ) を管理することもできます。少なくとも、このポリシーではユーザーを 1 つのリージョンに限定していますが、いかなる場合でも、テストは実稼働環境のプライマリーアカウントで実行すべきではありません。

en: Running Tests
ja: テストの実行

en: The tests are invoked via a ``Makefile``.
ja: テストは ``Makefile`` 経由で呼び出されます。

en: If you haven't already got Ansible available use the local checkout by doing::
ja: Ansible がまだ利用可能でない場合は、以下の方法でローカルチェックアウトを使用します。

en: Run the tests by doing::
ja: 以下を実行してテストを実行します。

en: Possible cost of running cloud tests
ja: クラウドテストにかかる可能性のあるコスト

en: Running cloud integration tests will create and destroy cloud resources. Running these tests may result in additional fees associated with your cloud account. Care is taken to ensure that created resources are removed. However, it is advisable to inspect your AWS console to ensure no unexpected resources are running.
ja: クラウド統合テストを実行すると、クラウドリソースが作成および破棄されます。このようなテストを実行すると、クラウドアカウントに関連する追加料金が発生する可能性があります。作成されたリソースが確実に削除されるように注意が払われます。ただし、AWS コンソールを調べて、予期しないリソースが実行していないことを確認することが推奨されます。

en: `PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the repository by default.
ja: `PEP 8`_ スタイルのガイドラインは、デフォルトでリポジトリーにあるすべての python ファイルで `pycodestyle`_ によって強制されます。

en: Running Locally
ja: ローカルでの実行

en: The `PEP 8`_ check can be run locally with::
ja: `PEP 8`_ チェックは、以下を使用してローカルで実行できます。

en: This document describes how to:
ja: 本書では、以下を行う方法を説明します。

en: Run tests locally using ``ansible-test``
ja: ``ansible-test`` を使用してテストをローカルで実行します。

en: Extend
ja: 拡張

en: There are no special requirements for running ``ansible-test`` on Python 2.7 or later. The ``argparse`` package is required for Python 2.6. The requirements for each ``ansible-test`` command are covered later.
ja: Python 2.7 以降には、``ansible-test`` を実行するための特別な要件がありません。Python 2.6 には ``argparse`` パッケージが必要です。各 ``ansible-test`` コマンドの要件は、後で説明します。

en: Test Environments
ja: テスト環境

en: Most ``ansible-test`` commands support running in one or more isolated test environments to simplify testing.
ja: ほとんどの ``ansible-test`` コマンドは、テストを簡単にするために、1 つ以上の分離テスト環境での実行をサポートします。

en: Remote
ja: リモート

en: The ``--remote`` option runs tests in a cloud hosted environment. An API key is required to use this feature.
ja: ``--remote`` オプションは、クラウドホスト環境でテストを実行します。この機能を使用するには API キーが必要です。

en: Recommended for integration tests.
ja: 統合テストへ推奨事項

en: See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/remote.txt>`_ for additional details.
ja: 詳細は、「`サポート対象のプラットフォームおよびバージョンの一覧 <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/remote.txt>`_」を参照してください。

en: Environment Variables
ja: 環境変数

en: When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
ja: 環境変数を使用してテストを操作する際には、以下の制限事項に留意してください。環境変数は以下のようになります。

en: Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options.
ja: ``--docker`` オプションまたは ``--remote`` オプションを使用する場合は、ホストからテスト環境に伝播されません。

en: Not exposed to the test environment unless enabled in ``test/lib/ansible_test/_internal/util.py`` in the ``common_environment`` function.
ja: ``common_environment`` 関数の ``test/lib/ansible_test/_internal/util.py`` で有効にされていない限り、テスト環境には公開されません。

en: Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --venv``. However, using the ``--docker`` option would require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set and the tests executed. This is useful for debugging tests inside a container by following the :ref:`Debugging AnsibleModule-based modules <debugging_modules>` instructions.
ja: 例: ``ansible-test integration --venv`` の実行時に ``ANSIBLE_KEEP_REMOTE_FILES=1`` を設定できますが、``--docker`` オプションを使用すると、``ansible-test shell`` を実行し、Docker 環境へのアクセスが必要になります。シェルプロンプトでは、環境変数を設定してテストを行う可能性があります。これは、:ref:`Debugging AnsibleModule-based modules <debugging_modules>` の指示に従って、コンテナー内でテストをデバッグする上で役立ちます。

en: Interactive Shell
ja: インタラクティブシェル

en: Use the ``ansible-test shell`` command to get an interactive shell in the same environment used to run tests. Examples:
ja: ``ansible-test shell`` コマンドを使用して、テストを実行するのに使用する同じ環境でインタラクティブシェルを取得します。以下は例になります。

en: ``ansible-test shell --docker`` - Open a shell in the default docker container.
ja: ``ansible-test shell --docker`` - デフォルトの docker コンテナーでシェルを開きます。

en: ``ansible-test shell --venv --python 3.6`` - Open a shell in a Python 3.6 virtual environment.
ja: ``ansible-test shell --venv --python 3.6`` - Python 3.6 仮想環境でシェルを開きます。

en: Code Coverage
ja: コードの対象範囲

en: Code coverage reports make it easy to identify untested code for which more tests should be written.  Online reports are available but only cover the ``devel`` branch (see :ref:`developing_testing`).  For new code local reports are needed.
ja: コードの対象範囲レポートは、より多くのテストが記述されるべき未テストのコードを簡単に識別することができます。オンラインレポートが利用できますが、``devel`` ブランチのみを扱います (:ref:`developing_testing` を参照)。新規コードのローカルレポートが必要な場合は、以下を行います。

en: Add the ``--coverage`` option to any test command to collect code coverage data.  If you aren't using the ``--venv`` or ``--docker`` options which create an isolated python environment then you may have to use the ``--requirements`` option to ensure that the correct version of the coverage module is installed::
ja: コードカバレッジデータを収集するテストコマンドに ``--coverage`` オプションを追加します。分離した python 環境を作成する ``--venv`` オプションまたは ``--docker`` オプションを使用していない場合は、``--requirements`` オプションを使用してカバレッジモジュールの正しいバージョンがインストールされていることを確認する必要があります。

en: Reports can be generated in several different formats:
ja: Report は、複数の形式で生成できます。

en: ``ansible-test coverage report`` - Console report.
ja: ``ansible-test coverage report`` - コンソールレポート。

en: ``ansible-test coverage html`` - HTML report.
ja: ``ansible-test coverage html`` - HTML レポート。

en: ``ansible-test coverage xml`` - XML report.
ja: ``ansible-test coverage xml`` - XML レポート。

en: To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help::
ja: テスト実行間のデータを消去するには、``ansible-test coverage erase`` コマンドを使用します。機能の全一覧については、オンラインヘルプを参照してください。

en: Sanity tests are made up of scripts and tools used to perform static code analysis. The primary purpose of these tests is to enforce Ansible coding standards and requirements.
ja: 健全性テストは、静的コード分析の実行に使用されるスクリプトおよびツールで構成されています。これらのテストの主な目的は、Ansible コーディングの仕様および要件を適用することです。

en: Tests are run with ``ansible-test sanity``. All available tests are run unless the ``--test`` option is used.
ja: テストは、``ansible-test sanity`` で実行します。``--test`` オプションを使用しない限り、利用可能なテストはすべて実行します。

en: How to run
ja: 実行方法

en: To run sanity tests using docker, always use the default docker image by passing the ``--docker`` or ``--docker default`` argument.
ja: docker を使用して健常性テストを実行するには、常に ``--docker`` 引数または ``--docker default`` 引数を渡すことでデフォルトの docker イメージを常に使用します。

en: When using docker and the ``--base-branch`` argument, also use the ``--docker-keep-git`` argument to avoid git related errors.
ja: docker および ``--base-branch`` 引数を使用する場合は、git 関連のエラーを回避するために ``--docker-keep-git`` 引数も使用します。

en: Available Tests
ja: 利用可能なテスト

en: Tests can be listed with ``ansible-test sanity --list-tests``.
ja: テストは ``ansible-test sanity --list-tests`` で一覧表示できます。

en: See the full list of :ref:`sanity tests <all_sanity_tests>`, which details the various tests and details how to fix identified issues.
ja: 各種テストや特定された問題を解決する方法の詳細は、「:ref:`健全性テスト <all_sanity_tests>`」の一覧を参照してください。

en: Unit Tests
ja: ユニットテスト

en: Unit tests are small isolated tests that target a specific library or module.  Unit tests in Ansible are currently the only way of driving tests from python within Ansible's continuous integration process. This means that in some circumstances the tests may be a bit wider than just units.
ja: ユニットテストは、特定のライブラリーまたはモジュールを対象とする小規模の分離テストです。現在、Ansible のユニットテストは、Ansible の継続的統合プロセスの中で、python からテストを実行する唯一の方法です。つまり、状況によっては、テストにはユニット以外のものも含まれる場合があることを意味します。

en: Unit tests can be found in `test/units <https://github.com/ansible/ansible/tree/devel/test/units>`_. Notice that the directory structure of the tests matches that of ``lib/ansible/``.
ja: ユニットテストは `test/units <https://github.com/ansible/ansible/tree/devel/test/units>`_ にあります。テストのディレクトリー構造が ``lib/ansible/`` と一致することに注意してください。

en: To run unit tests using docker, always use the default docker image by passing the ``--docker`` or ``--docker default`` argument.
ja: docker を使用してユニットテストを実行するには、``--docker`` 引数または ``--docker default`` 引数を渡すことで常にデフォルトの docker イメージを使用します。

en: The Ansible unit tests can be run across the whole code base by doing:
ja: Ansible のユニットテストは、以下の操作を実行してコードベース全体で実行できます。

en: If you are running unit tests against things other than modules, such as module utilities, specify the whole file path:
ja: モジュールユーティリティーなどのモジュール以外のものに対してユニットテストを実行している場合は、ファイルパス全体を指定します。

en: For advanced usage see the online help::
ja: 高度な使用方法は、オンラインヘルプを参照してください。

en: You can also run tests in Ansible's continuous integration system by opening a pull request.  This will automatically determine which tests to run based on the changes made in your pull request.
ja: プル要求を開いて、Ansible の継続的統合システムでテストを実行することもできます。これにより、プル要求で実行された変更に基づいて、実行されるテストが自動的に決定されます。

en: If you are running ``ansible-test`` with the ``--docker`` or ``--venv`` option you do not need to install dependencies manually.
ja: ``--docker`` オプションまたは ``--venv`` オプションを指定して ``ansible-test`` を実行している場合は、依存関係を手動でインストールする必要はありません。

en: Otherwise you can install dependencies using the ``--requirements`` option, which will install all the required dependencies needed for unit tests. For example:
ja: それ以外の場合は、``--requirements`` オプションを使用して依存関係をインストールし、ユニットテストに必要な依存関係をすべてインストールします。以下に例を示します。

en: The list of unit test requirements can be found at `test/units/requirements.txt <https://github.com/ansible/ansible/tree/devel/test/units/requirements.txt>`_.
ja: ユニットテストの要件一覧は、`test/units/requirements.txt <https://github.com/ansible/ansible/tree/devel/test/units/requirements.txt>`_ を参照してください。

en: This does not include the list of unit test requirements for ``ansible-test`` itself, which can be found at `test/lib/ansible_test/_data/requirements/units.txt <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements/units.txt>`_.
ja: これには、``ansible-test`` のユニットテスト要件のリストは含まれていません。それは、`test/lib/ansible_test/_data/requirements/units.txt <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements/units.txt>`_ で見つけることができます。

en: See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ applicable to all test commands.
ja: すべてのコマンドに適用可能な「`制約 <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_」も参照してください。

en: Extending unit tests
ja: ユニットテストの拡張

en: What a unit test isn't
ja: ユニットテスト以外のもの

en: If you start writing a test that requires external services then you may be writing an integration test, rather than a unit test.
ja: 外部サービスを必要とするテストを書き始めると、ユニットテストではなく統合テストを書くことができます。

en: Structuring Unit Tests
ja: ユニットテストの構造

en: Ansible drives unit tests through `pytest <https://docs.pytest.org/en/latest/>`_. This means that tests can either be written a simple functions which are included in any file name like ``test_<something>.py`` or as classes.
ja: Ansible は、`pytest <https://docs.pytest.org/en/latest/>`_ でユニットテストを行います。これは、テストは、``test_<something>.py`` のファイル名またはクラスとして含まれる単純な関数を記述できることを意味します。

en: Here is an example of a function::
ja: 以下は、関数の例です。

en: Here is an example of a class::
ja: 以下はクラスの例です。

en: Both methods work fine in most circumstances; the function-based interface is simpler and quicker and so that's probably where you should start when you are just trying to add a few basic tests for a module.  The class-based test allows more tidy set up and tear down of pre-requisites, so if you have many test cases for your module you may want to refactor to use that.
ja: どちらの方法も、ほとんどの状況で正常に機能します。関数ベースのインターフェースの方がシンプルで速いため、モジュールにいくつかの基本的なテストを追加しようとしている場合は、ここから始めることが推奨されます。クラスベースのテストでは、前提条件の設定や分解をより整然と行うことができるため、モジュールに多くのテストケースがある場合は、それを使用するようにリファクタリングすることが推奨されます。

en: Assertions using the simple ``assert`` function inside the tests will give full information on the cause of the failure with a trace-back of functions called during the assertion.  This means that plain asserts are recommended over other external assertion libraries.
ja: テスト内の簡単な ``assert`` 関数を使用するアサーションにより、アサーション中に呼び出される関数のトレースバックで障害に関する完全な情報が表示されます。これは、他の外部アサーションライブラリーよりも、プレーンアサートが推奨されることを意味します。

en: A number of the unit test suites include functions that are shared between several modules, especially in the networking arena.  In these cases a file is created in the same directory, which is then included directly.
ja: 多くのユニットテストスイートには、特にネットワークの分野では、複数のモジュールで共有される関数が含まれています。この場合は、同じディレクトリーにファイルが作成されます。このファイルは、直接含まれます。

en: Module test case common code
ja: モジュールテストケースの共通コード

en: Keep common code as specific as possible within the `test/units/` directory structure. Don't import common unit test code from directories outside the current or parent directories.
ja: `test/units/` ディレクトリー構造内で可能な限り具体的に共通コードを維持します。現在のディレクトリーまたは親ディレクトリー以外のディレクトリーから共通のユニットテストコードをインポートしないでください。

en: Don't import other unit tests from a unit test. Any common code should be in dedicated files that aren't themselves tests.
ja: ユニットテストから他のユニットテストをインポートしないでください。共通のコードは、テスト自体ではない専用のファイルに含める必要があります。

en: Fixtures files
ja: Fixtures ファイル

en: To mock out fetching results from devices, or provide other complex data structures that come from external libraries, you can use ``fixtures`` to read in pre-generated data.
ja: デバイスからの結果の取得を模倣したり、外部ライブラリーから取得した他の複雑なデータ構造を提供するために、``fixtures`` を使用して事前に生成されたデータを読み込むことができます。

en: You can check how `fixtures <https://github.com/ansible/ansible/tree/devel/test/units/module_utils/facts/fixtures/cpuinfo>`_ are used in `cpuinfo fact tests <https://github.com/ansible/ansible/blob/9f72ff80e3fe173baac83d74748ad87cb6e20e64/test/units/module_utils/facts/hardware/linux_data.py#L384>`_
ja: `cpuinfo ファクトテスト <https://github.com/ansible/ansible/blob/9f72ff80e3fe173baac83d74748ad87cb6e20e64/test/units/module_utils/facts/hardware/linux_data.py#L384>`_ で、`fixtures <https://github.com/ansible/ansible/tree/devel/test/units/module_utils/facts/fixtures/cpuinfo>`_ が使用される方法を確認することができます。

en: If you are simulating APIs you may find that Python placebo is useful.  See :ref:`testing_units_modules` for more information.
ja: API のシミュレーションをしているのであれば、Python のプラシーボが役に立つかもしれません。詳細は、「:ref:`testing_units_modules`」を参照してください。

en: Code Coverage For New or Updated Unit Tests
ja: 新規ユニットテストまたは更新されたユニットテスト用のコード対応

en: New code will be missing from the codecov.io coverage reports (see :ref:`developing_testing`), so local reporting is needed.  Most ``ansible-test`` commands allow you to collect code coverage; this is particularly useful when to indicate where to extend testing.
ja: codecov.io カバレッジレポートから新しいコードが欠落し (:ref:`developing_testing`を参照)、ローカルレポートが必要です。ほとんどの ``ansible-test`` コマンドを使用すると、コードカバレッジを収集できます。これは、テストを拡張する場所を示すときに特に役立ちます。

en: To collect coverage data add the ``--coverage`` argument to your ``ansible-test`` command line:
ja: カバレージデータを収集するには、``--coverage`` 引数を ``ansible-test`` コマンドラインに追加します。

en: Results will be written to ``test/results/reports/coverage/index.html``
ja: 結果は ``test/results/reports/coverage/index.html`` に書き込まれます。

en: To clear data between test runs, use the ``ansible-test coverage erase`` command.  See :ref:`testing_running_locally` for more information about generating coverage reports.
ja: テスト実行間のデータを消去するには、``ansible-test coverage erase`` コマンドを使用します。カバレッジレポートの生成の詳細は、「:ref:`testing_running_locally`」を参照してください。

en: Special considerations for unit testing modules
ja: ユニットテストモジュールに関する特別な考慮事項

en: Running tests locally including gathering and reporting coverage data
ja: カバレージデータの収集とレポートを含む、ローカルでのテストの実行

en: The documentation of the unittest framework in python 3
ja: Python 3 におけるユニットテストフレームワークのドキュメント

en: The documentation of the earliest supported unittest framework - from Python 2.6
ja: サポートされている初期のユニットテストフレームワークのドキュメント (Python 2.6)

en: The documentation of pytest - the framework actually used to run Ansible unit tests
ja: pytest のドキュメント - Ansible ユニットテストの実行に実際に使用されているフレームワーク

en: Unit Testing Ansible Modules
ja: Ansible モジュールのユニットテスト

en: This document explains why, how and when you should use unit tests for Ansible modules. The document doesn't apply to other parts of Ansible for which the recommendations are normally closer to the Python standard. There is basic documentation for Ansible unit tests in the developer guide :ref:`testing_units`. This document should be readable for a new Ansible module author. If you find it incomplete or confusing, please open a bug or ask for help on Ansible IRC.
ja: このドキュメントでは、Ansible モジュールにユニットテストを使用する理由、方法、タイミングを説明します。このドキュメントは、通常 Python の標準に近い推奨事項を持つ Ansible の他の部分には適用されません。Ansible のユニットテストに関する基本的なドキュメントは、開発者ガイドの「:ref:`testing_units`」にあります。このドキュメントは、新しい Ansible モジュールの作成者にとって読みやすいものでなければなりません。不完全だったり、分かりにくかったりした場合は、バグを報告したり、Ansible IRC で助けを求めたりしてください。

en: What Are Unit Tests?
ja: ユニットテストとは

en: Ansible includes a set of unit tests in the :file:`test/units` directory. These tests primarily cover the internals but can also cover Ansible modules. The structure of the unit tests matches the structure of the code base, so the tests that reside in the :file:`test/units/modules/` directory are organized by module groups.
ja: Ansible には、:file:`test/units` ディレクトリーにユニットテストのセットが含まれています。これらのテストは、主に内部に対応していますが、Ansible モジュールにも対応します。ユニットテストの構造はコードベースのベースの構造に一致し、:file:`test/units/modules/` ディレクトリーに含まれるテストはモジュールグループごとに編成されます。

en: Integration tests can be used for most modules, but there are situations where cases cannot be verified using integration tests. This means that Ansible unit test cases may extend beyond testing only minimal units and in some cases will include some level of functional testing.
ja: 統合テストはほとんどのモジュールで使用できますが、統合テストではケースを検証できない場合もあります。つまり、Ansible ユニットテストケースは、最小限のユニットのみのテストにとどまらず、場合によっては、ある程度の機能テストが含まれることもあります。

en: Why Use Unit Tests?
ja: ユニットテストを使用する理由

en: Ansible unit tests have advantages and disadvantages. It is important to understand these. Advantages include:
ja: Ansible ユニットテストには長所と短所があり、その点を理解することは重要です。以下が挙げられます。

en: Most unit tests are much faster than most Ansible integration tests. The complete suite of unit tests can be run regularly by a developer on their local system.
ja: ほとんどのユニットテストは、ほとんどの Ansible 統合テストよりもはるかに高速です。ユニットテストの完全なスイートは、ローカルシステムで開発者が定期的に実行できます。

en: Unit tests can be run by developers who don't have access to the system which the module is designed to work on, allowing a level of verification that changes to core functions haven't broken module expectations.
ja: ユニットテストは、モジュールが動作するように設計されているシステムにアクセスできない開発者が実行することができ、コア機能への変更がモジュールの期待どおりであることをある程度検証できます。

en: Unit tests can easily substitute system functions allowing testing of software that would be impractical. For example, the ``sleep()`` function can be replaced and we check that a ten minute sleep was called without actually waiting ten minutes.
ja: ユニットテストは、システム関数を簡単に置換でき、実現するソフトウェアのテストを簡単に指定することができます。たとえば、``sleep()`` 関数を置き換えることができ、実際に 10 分待たずに 10 分のスリープが呼び出されたことを確認します。

en: Unit tests are run on different Python versions. This allows us to ensure that the code behaves in the same way on different Python versions.
ja: ユニットテストは、Python の各バージョンで実行されます。これにより、コードが異なる Python のバージョンでも同じように動作することを確認できます。

en: There are also some potential disadvantages of unit tests. Unit tests don't normally directly test actual useful valuable features of software, instead just internal implementation
ja: ユニットテストには、いくつかの潜在的な欠点もあります。通常、実際に便利で価値のある機能を直接テストせず、代わりに内部実装をテストします。

en: Unit tests that test the internal, non-visible features of software may make refactoring difficult if those internal features have to change (see also naming in How below)
ja: ソフトウェア内部にある、目に見えない機能をテストするユニットテストは、それらの内部機能を変更する必要がある場合、リファクタリングを困難にする可能性があります (以下の「方法」の命名も参照)。

en: Even if the internal feature is working correctly it is possible that there will be a problem between the internal code tested and the actual result delivered to the user
ja: 内部機能が正しく機能している場合でも、テストされた内部コードとユーザーに配信される実際の結果との間に問題が発生する可能性があります。

en: Normally the Ansible integration tests (which are written in Ansible YAML) provide better testing for most module functionality. If those tests already test a feature and perform well there may be little point in providing a unit test covering the same area as well.
ja: 通常、(Ansible YAML で記述される) Ansible 統合テストは、ほとんどのモジュール機能に対してより良いテストを提供します。これらのテストがすでに機能をテストしていて、うまく機能している場合は、同じ領域をカバーするユニットテストを提供する意味はほとんどないかもしれません。

en: When To Use Unit Tests
ja: ユニットテストを使用するタイミング

en: There are a number of situations where unit tests are a better choice than integration tests. For example, testing things which are impossible, slow or very difficult to test with integration tests, such as:
ja: 統合テストよりもユニットテストの方が適している状況は数多くあります。たとえば、次のような統合テストでテストすることが不可能で、遅い、または非常に難しいものをテストします。

en: Forcing rare / strange / random situations that can't be forced, such as specific network failures and exceptions
ja: 特定のネットワーク障害や例外のような、強制することができない稀な、奇妙な、およびランダムな状況を強制。

en: Extensive testing of slow configuration APIs
ja: 遅い設定 API の広範なテスト

en: Situations where the integration tests cannot be run as part of the main Ansible continuous integration running in Azure Pipelines.
ja: Azure Pipeline で実行されているメインの Ansible 継続的統合の一部として、統合テストを実行できない状況。

en: Providing quick feedback
ja: 迅速なフィードバックの提供

en: A single step of the rds_instance test cases can take up to 20 minutes (the time to create an RDS instance in Amazon). The entire test run can last for well over an hour. All 16 of the unit tests complete execution in less than 2 seconds.
ja: rds_instance のテストケースの 1 つのステップには、最大 20 分 (Amazonで RDS インスタンスを作成する時間) かかる場合があります。テストの実行は、全体で 1 時間以上かかることもあります。16 個のユニットテストは、すべて 2 秒以内に実行を完了します。

en: The time saving provided by being able to run the code in a unit test makes it worth creating a unit test when bug fixing a module, even if those tests do not often identify problems later. As a basic goal, every module should have at least one unit test which will give quick feedback in easy cases without having to wait for the integration tests to complete.
ja: ユニットテストでコードを実行できることによって提供される時間の節約により、モジュールのバグ修正時にユニットテストを作成する価値があります。これらのテストで後で問題が特定されることはあまりありません。基本的な目標として、すべてのモジュールには少なくとも 1 つのユニットテストが必要です。これにより、統合テストが完了するのを待たずに、簡単なケースで迅速なフィードバックが得られます。

en: Ensuring correct use of external interfaces
ja: 外部インターフェースを正しく使用すること

en: Unit tests can check the way in which external services are run to ensure that they match specifications or are as efficient as possible *even when the final output will not be changed*.
ja: ユニットテストは、*最終的な出力が変更されない場合でも*、外部サービスの実行方法が仕様に合致しているか、あるいは可能な限り効率的であるかを確認できます。

en: Package managers are often far more efficient when installing multiple packages at once rather than each package separately. The final result is the same: the packages are all installed, so the efficiency is difficult to verify through integration tests. By providing a mock package manager and verifying that it is called once, we can build a valuable test for module efficiency.
ja: パッケージマネージャーは、各パッケージを個別にインストールするよりも、複数のパッケージを一度にインストールする方がはるかに効率的であることがよくあります。最終結果は同じです。すべてのパッケージがインストールされるため、統合テストで効率を検証することは困難です。模擬パッケージマネージャを提供し、それが一度に呼ばれることを検証するため、モジュール効率について貴重なテストを構築できます。

en: Another related use is in the situation where an API has versions which behave differently. A programmer working on a new version may change the module to work with the new API version and unintentionally break the old version. A test case which checks that the call happens properly for the old version can help avoid the problem. In this situation it is very important to include version numbering in the test case name (see `Naming unit tests`_ below).
ja: 別の関連する使用法は、API の動作が異なるバージョンがある状況です。新しいバージョンで作業しているプログラマーは、新しい API バージョンで動作するようにモジュールを変更し、意図せずに古いバージョンを壊してしまう可能性があります。古いバージョンで呼び出しが適切に行われることを確認するテストケースは、問題を回避するのに役立ちます。この状況では、テストケース名にバージョン番号を含めることが非常に重要です (以下 `Naming unit tests`_ を参照)。

en: Providing specific design tests
ja: 特定の設計テストの提供

en: By building a requirement for a particular part of the code and then coding to that requirement, unit tests _can_ sometimes improve the code and help future developers understand that code.
ja: コードの特定の部分に対する要件を構築し、その要件に合わせてコーディングすることで、ユニットテストは、時にはコードを改善し、将来の開発者がそのコードを理解する助けとなります。

en: Unit tests that test internal implementation details of code, on the other hand, almost always do more harm than good.  Testing that your packages to install are stored in a list would slow down and confuse a future developer who might need to change that list into a dictionary for efficiency. This problem can be reduced somewhat with clear test naming so that the future developer immediately knows to delete the test case, but it is often better to simply leave out the test case altogether and test for a real valuable feature of the code, such as installing all of the packages supplied as arguments to the module.
ja: 一方、コードの内部実装の詳細をテストするユニットテストは、ほとんどの場合、益よりも害をもたらします。インストールするパッケージがリストに格納されているかどうかをテストすると、遅くなり、効率化のためにリストをディクショナリーに変更しないといけない将来の開発者を混乱させます。この問題は、将来の開発者がすぐにテストケースを削除することがわかるように、明確なテスト名をつけることで多少軽減できますが、単にテストケースを完全に除外して、モジュールの引数として与えられたすべてのパッケージをインストールするなど、コードの本当の価値ある機能をテストする方が良い場合が多いです。

en: How to unit test Ansible modules
ja: Ansible モジュールをユニットテストする方法

en: There are a number of techniques for unit testing modules. Beware that most modules without unit tests are structured in a way that makes testing quite difficult and can lead to very complicated tests which need more work than the code. Effectively using unit tests may lead you to restructure your code. This is often a good thing and leads to better code overall. Good restructuring can make your code clearer and easier to understand.
ja: ユニットテストモジュールにはいくつかの手法があります。ユニットテストのないほとんどのモジュールでは、テストが非常に困難になり、コードよりも多くの作業が必要な、非常に複雑なテストにつながる可能性があることに注意してください。ユニットテストを効果的に使用するには、コードを再構築する可能性があります。これは多くの場合良いことであり、全体的に優れたコードにつながります。適切な再構築により、コードがより明確になり、理解しやすくなります。

en: Naming unit tests
ja: ユニットテストの命名

en: Unit tests should have logical names. If a developer working on the module being tested breaks the test case, it should be easy to figure what the unit test covers from the name. If a unit test is designed to verify compatibility with a specific software or API version then include the version in the name of the unit test.
ja: ユニットテストは論理名を付ける必要があります。テスト対象のモジュールで作業している開発者がテストケースを壊してしまった場合に、ユニットテストが何を対象としているのかが名前から簡単に分かるようにする必要があります。ユニットテストが特定のソフトウェアや API のバージョンとの互換性を検証するように設計されている場合は、ユニットテストの名前にそのバージョンを追加してください。

en: As an example, ``test_v2_state_present_should_call_create_server_with_name()`` would be a good name, ``test_create_server()`` would not be.
ja: たとえば、``test_v2_state_present_should_call_create_server_with_name()`` が適切な名前で、``test_create_server()`` は適切ではありません。

en: Use of Mocks
ja: モックの使用

en: Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very useful in building unit tests for special / difficult cases, but they can also lead to complex and confusing coding situations. One good use for mocks would be in simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use ``import units.compat.mock``).
ja: (https://docs.python.org/3/library/unittest.mock.html_ からの) モックオブジェクトは、特殊なケースや困難なケースのユニットテストを構築するのに非常に便利ですが、複雑で理解しづらいコーディングになってしまうこともあります。モックの使用方法として適切なものの 1 つに、API のシミュレートがあります。Python パッケージの「six」、「mock」は、Ansible にバンドルされています (``import units.compat.mock`` を使用)。

en: Ensuring failure cases are visible with mock objects
ja: モックオブジェクトで障害ケースを確実に可視化

en: Functions like :meth:`module.fail_json` are normally expected to terminate execution. When you run with a mock module object this doesn't happen since the mock always returns another mock from a function call. You can set up the mock to raise an exception as shown above, or you can assert that these functions have not been called in each test. For example::
ja: :meth:`module.fail_json` などの関数は、通常、実行を終了することが期待されます。モックモジュールオブジェクトを使用して実行すると、モックは常に関数呼び出しから別のモックを返すため、このようなことは起こりません。上記のように例外を発生させるようにモックを設定することもできますし、各テストでこれらの関数が呼び出されていないことをアサートすることもできます。以下に例を示します。

en: This applies not only to calling the main module but almost any other function in a module which gets the module object.
ja: これは、メインモジュールを呼び出す場合だけでなく、モジュールオブジェクトを取得するモジュール内の他のほとんどの関数を呼び出す場合にも適用されます。

en: Mocking of the actual module
ja: 実際のモジュールのモック化

en: The setup of an actual module is quite complex (see `Passing Arguments`_ below) and often isn't needed for most functions which use a module. Instead you can use a mock object as the module and create any module attributes needed by the function you are testing. If you do this, beware that the module exit functions need special handling as mentioned above, either by throwing an exception or ensuring that they haven't been called. For example::
ja: 実際のモジュールの設定は非常に複雑で (以下の `Passing Arguments`_ を参照)、モジュールを使用するほとんどの機能には必要ありません。モックオブジェクトをモジュールとして使用する代わりに、テストする関数で必要なモジュール属性を作成できます。この場合、モジュールの終了関数は、上述のように、例外を発生させるか、呼び出されていないことを確認するなど、特別な処理が必要になることに注意してください。以下に例を示します。

en: API definition with unit test cases
ja: ユニットテストケースでの API 定義

en: API interaction is usually best tested with the function tests defined in Ansible's integration testing section, which run against the actual API. There are several cases where the unit tests are likely to work better.
ja: API の対話は通常、実際の API に対して実行する Ansible の統合テストセクションで定義された関数テストでテストを行うのが最適です。ユニットテストが適切に機能する可能性があります。

en: Defining a module against an API specification
ja: API の仕様に対してモジュールを定義

en: This case is especially important for modules interacting with web services, which provide an API that Ansible uses but which are beyond the control of the user.
ja: このケースは、Ansible が使用する API を提供しているが、ユーザーの制御が及ばない Web サービスと対話するモジュールにとって特に重要になります。

en: By writing a custom emulation of the calls that return data from the API, we can ensure that only the features which are clearly defined in the specification of the API are present in the message. This means that we can check that we use the correct parameters and nothing else.
ja: API からデータを返す呼び出しのカスタムエミュレーションを書くことで、API の仕様で明確に定義されている機能のみがメッセージに含まれていることを確認できます。つまり、正しいパラメーターを使用しているかどうかを確認し、それ以外は何も使用していないことを確認することができます。

en: *Example:  in rds_instance unit tests a simple instance state is defined*::
ja: *例: rds_instance ユニットテストでは、単純なインスタンスの状態が定義されています*::

en: This is then used to create a list of states::
ja: 次に、これを使用して状態のリストを作成します。

en: These states are then used as returns from a mock object to ensure that the ``await`` function waits through all of the states that would mean the RDS instance has not yet completed configuration::
ja: これらの状態は、モックオブジェクトからの戻り値として使用され、``await`` 関数は、RDS インスタンスがまだ設定を完了しないことを意味するすべての状態を待機します。

en: By doing this we check that the ``await`` function will keep waiting through potentially unusual that it would be impossible to reliably trigger through the integration tests but which happen unpredictably in reality.
ja: これを実行することで、統合テストでは確実に誘発させることができないにもかかわらず、現実には予測できないような、潜在的に異常なことが起こる可能性がある場合に ``await`` 関数が待機し続けるかどうかを確認します。

en: Defining a module to work against multiple API versions
ja: 複数の API バージョンに対して動作するモジュールの定義

en: This case is especially important for modules interacting with many different versions of software; for example, package installation modules that might be expected to work with many different operating system versions.
ja: このケースは、多くの異なるバージョンのソフトウェアと対話するモジュールにとって特に重要です。たとえば、さまざまなオペレーティングシステムのバージョンと動作することが想定されるパッケージインストールモジュールなどです。

en: By using previously stored data from various versions of an API we can ensure that the code is tested against the actual data which will be sent from that version of the system even when the version is very obscure and unlikely to be available during testing.
ja: さまざまなバージョンの API から、以前に保存されたデータを使用することで、バージョンが非常に曖昧でテスト中に利用できそうにない場合でも、そのバージョンのシステムから送信される実際のデータに対してコードがテストできるようになります。

en: Ansible special cases for unit testing
ja: Ansible ユニットテストの特殊なケース

en: There are a number of special cases for unit testing the environment of an Ansible module. The most common are documented below, and suggestions for others can be found by looking at the source code of the existing unit tests or asking on the Ansible IRC channel or mailing lists.
ja: Ansible モジュールの環境に対してユニットテストを行うための特別なケースがいくつかあります。最も一般的なものを以下に示します。他の人への提案は、既存のユニットテストのソースコードを確認するか、Ansible IRC チャンネルまたはメーリングリストで質問することで見つけることができます。

en: Module argument processing
ja: モジュール引数処理

en: There are two problems with running the main function of a module:
ja: モジュールの主な関数の実行には、以下の 2 つの問題があります。

en: Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to set up the arguments correctly so that the module will get them as parameters.
ja: モジュールは ``STDIN`` で引数を受け入れる必要があるため、引数を正しく設定してモジュールがパラメーターとして受け取るようにするのは少し難しくなります。

en: All modules should finish by calling either the :meth:`module.fail_json` or :meth:`module.exit_json`, but these won't work correctly in a testing environment.
ja: すべてのモジュールは、:meth:`module.fail_json` または :meth:`module.exit_json` を呼び出して終了する必要がありますが、テスト環境では正常に動作しません。

en: Passing Arguments
ja: 引数の渡し方

en: To pass arguments to a module correctly, use the ``set_module_args`` method which accepts a dictionary as its parameter. Module creation and argument processing is handled through the :class:`AnsibleModule` object in the basic section of the utilities. Normally this accepts input on ``STDIN``, which is not convenient for unit testing. When the special variable is set it will be treated as if the input came on ``STDIN`` to the module. Simply call that function before setting up your module::
ja: モジュールに正しく引数を渡すには、ディクショナリーをパラメーターとして受け付ける ``set_module_args`` メソッドを使用します。モジュールの作成と引数の処理は、ユーティリティーの基本セクションにある :class:`AnsibleModule` オブジェクトによって処理されます。通常は ``STDIN`` で入力を受け付けますが、これはユニットテストには不便です。特殊変数が設定されると、あたかも入力が ``STDIN`` でモジュールに来たかのように扱われます。モジュールをセットアップする前にこの関数を呼び出すだけです。

en: Handling exit correctly
ja: 終了を適切に処理

en: The :meth:`module.exit_json` function won't work properly in a testing environment since it writes error information to ``STDOUT`` upon exit, where it is difficult to examine. This can be mitigated by replacing it (and :meth:`module.fail_json`) with a function that raises an exception::
ja: :meth:`module.exit_json` 関数は、終了時にエラー情報を ``STDOUT`` に書き込むため、テスト環境で適切に動作しません。これは検証が困難です。これは、この関数 (および :meth:`module.fail_json`) を、例外を発生させる関数に置き換えることで軽減できます。

en: Now you can ensure that the first function called is the one you expected simply by testing for the correct exception::
ja: これで、正しい例外をテストするだけで、最初に呼び出された関数が期待したものであることを確認できるようになりました。

en: The same technique can be used to replace :meth:`module.fail_json` (which is used for failure returns from modules) and for the ``aws_module.fail_json_aws()`` (used in modules for Amazon Web Services).
ja: 同じテクニックを使用して、:meth:`module.fail_json` (モジュールから返る障害に使用) および ``aws_module.fail_json_aws()`` (Amazon Web Services のモジュールに使用) に置き換えることができます。

en: Running the main function
ja: 主な関数の実行

en: If you do want to run the actual main function of a module you must import the module, set the arguments as above, set up the appropriate exit exception and then run the module::
ja: モジュールにおける主な実関数を実行する場合は、モジュールをインポートし、上記のように引数を設定し、適切な終了例外を設定してからモジュールを実行する必要があります。

en: Handling calls to external executables
ja: 外部実行ファイルへの呼び出しの処理

en: Module must use :meth:`AnsibleModule.run_command` in order to execute an external command. This method needs to be mocked:
ja: モジュールは、外部コマンドを実行するのに :meth:`AnsibleModule.run_command` を使用する必要があります。このメソッドをモックする必要があります。

en: Here is a simple mock of :meth:`AnsibleModule.run_command` (taken from :file:`test/units/modules/packaging/os/test_rhn_register.py`)::
ja: 以下は、:meth:`AnsibleModule.run_command` (:file:`test/units/modules/packaging/os/test_rhn_register.py` から取得) の簡単なモックです。

en: A Complete Example
ja: 完全な例

en: The following example is a complete skeleton that reuses the mocks explained above and adds a new mock for :meth:`Ansible.get_bin_path`::
ja: 次の例は、上記で説明したモックを再利用し、:meth:`Ansible.get_bin_path` の新しいモックを追加する完全なスケルトンです。

en: Restructuring modules to enable testing module set up and other processes
ja: モジュールのセットアップやその他のプロセスのテストを可能にするモジュールの再構築

en: Often modules have a ``main()`` function which sets up the module and then performs other actions. This can make it difficult to check argument processing. This can be made easier by moving module configuration and initialization into a separate function. For example::
ja: 多くの場合、モジュールをセットアップし、他のアクションを実行する ``main()`` 関数があります。これにより、引数処理を確認するのが困難になる可能性があります。モジュールの設定と初期化を別の関数に移すことで簡単にできます。以下に例を示します。

en: This now makes it possible to run tests against the module initiation function::
ja: これにより、モジュールの開始関数に対してテストを実行できるようになりました。

en: See also ``test/units/module_utils/aws/test_rds.py``
ja: 「``test/units/module_utils/aws/test_rds.py``」も参照してください。

en: Note that the ``argument_spec`` dictionary is visible in a module variable. This has advantages, both in allowing explicit testing of the arguments and in allowing the easy creation of module objects for testing.
ja: ``argument_spec`` ディクショナリーはモジュール変数に表示されます。これには、引数の明示的なテストを許可し、テスト用にモジュールオブジェクトの作成を簡単に行えるようにする利点があります。

en: The same restructuring technique can be valuable for testing other functionality, such as the part of the module which queries the object that the module configures.
ja: この再構築の手法は、モジュールが設定したオブジェクトを問い合わせるモジュールの部分など、その他の機能をテストする場合にも役に立ちます。

en: Traps for maintaining Python 2 compatibility
ja: Python 2 の互換性を維持するためのトラップ

en: If you use the ``mock`` library from the Python 2.6 standard library, a number of the assert functions are missing but will return as if successful. This means that test cases should take great care *not* use functions marked as _new_ in the Python 3 documentation, since the tests will likely always succeed even if the code is broken when run on older versions of Python.
ja: Python 2.6 標準ライブラリーの ``mock`` ライブラリーを使用している場合は、多くの assert 関数が欠落していますが、成功したかのように返されます。これは、テストケースが、Python 3 のドキュメントで _new_ となっている関数を使用しないよう、細心の注意を払うべきであることを意味します。なぜなら、古いバージョンの Python で実行されたコードが壊れていても、テストは常に成功するからです。

en: A helpful development approach to this should be to ensure that all of the tests have been run under Python 2.6 and that each assertion in the test cases has been checked to work by breaking the code in Ansible to trigger that failure.
ja: これに役立つ開発アプローチは、すべてのテストが Python 2.6 で実行されていることと、テストケース内の各アサーションが Ansible でコードを壊してその失敗を誘発することで動作することが確認されているという点を確認することです。

en: Maintain Python 2.6 compatibility
ja: Python 2.6 互換性の維持

en: Please remember that modules need to maintain compatibility with Python 2.6 so the unittests for modules should also be compatible with Python 2.6.
ja: モジュールは Python 2.6 との互換性を維持する必要があるため、モジュールのユニットテストも、Python 2.6 との互換性を維持する必要があることに注意してください。

en: Ansible unit tests documentation
ja: Ansible ユニットテストドキュメント

en: Get started developing a module
ja: モジュール開発を始める

en: General advice on testing Python code
ja: Python コードのテストに関する一般的なアドバイス

en: Unit testing is a part of the of various philosophies of software development, including Extreme Programming (XP), Clean Coding.  Uncle Bob talks through how to benefit from this
ja: ユニットテストは、Extreme Programming (XP)、クリーンコーディングを含むソフトウェア開発のさまざまな哲学の一部です。Uncle Bob は、どのようにしてこの恩恵を受けることができるのかを説明します。

en: An article warning against the costs of unit testing
ja: ユニットテストの大半が無駄である理由

en: An response pointing to how to maintain the value of unit tests
ja: ユニットテストの価値を維持する方法を指摘した回答

en: Python program to help test or validate Ansible modules.
ja: Ansible モジュールのテストまたは検証に役立つ Python プログラム。

en: ``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :ref:`testing_sanity` for more information.
ja: ``validate-modules`` は、健全性テスト ``ansible-test`` のいずれかです。詳細は、「:ref:`testing_sanity`」を参照してください。

en: Originally developed by Matt Martz (@sivel)
ja: 本プログラムは、元々 Matt Martz (@sivel) 氏により開発されました。

en: Usage
ja: 使用法

en: Help
ja: ヘルプ

en: Extending validate-modules
ja: validate-modules の拡張

en: The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``.
ja: ``validate-modules`` ツールには、``DOCUMENTATION``、``RETURNS`` などの YAML ブロックの検証に使用される `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py>`_ があります。

en: Codes
ja: コード

en: **Error Code**
ja: **エラーコード**

en: **Type**
ja: **タイプ**

en: **Level**
ja: **レベル**

en: **Sample Message**
ja: **開始メッセージ**

en: Documentation
ja: ドキュメント

en: Error
ja: エラー

en: A feature is deprecated and supposed to be removed in the current or an earlier Ansible version
ja: 機能は非推奨となり、現行またはそれ以前の Ansible バージョンで削除される予定です。

en: Syntax
ja: 構文

en: Execution of the module did not result in initialization of AnsibleModule
ja: モジュールを実行しても、AnsibleModule は初期化されなかった。

en: A feature is deprecated and supposed to be removed in the current or an earlier collection version
ja: 機能は非推奨となり、現行またはそれ以前のバージョンのコレクションで削除される予定です。

en: A date before today appears as ``removed_at_date`` or in ``deprecated_aliases``
ja: 今日より前の日付は、``removed_at_date`` ように表示されるか、``deprecated_aliases`` に表示されます。

en: Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places.
ja: ファイル名、そのメタデータ、または DOCUMENTATION の少なくとも 1 つ (全箇所ではない) で非推奨または削除済みとしてマークされたモジュール (非推奨の場合は DOCUMENTATION.deprecated を設定し、削除の場合はすべてのドキュメントを削除する) します。

en: Value for "choices" from the argument_spec does not match the documentation
ja: argument_spec の「choices」の値がドキュメントと一致しない。

en: Choices value from the documentation is not compatible with type defined in the argument_spec
ja: ドキュメンテーションの選択値は、argument_spec で定義されたタイプと互換性がありません。

en: Value for "default" from the argument_spec does not match the documentation
ja: argument_spec の「default」の値がドキュメントと一致しない。

en: Default value from the documentation is not compatible with type defined in the argument_spec
ja: ドキュメンテーションのデフォルト値は、argument_spec で定義されたタイプと互換性がありません。

en: Documentation specifies elements for argument, when "type" is not ``list``.
ja: ドキュメントでは、「type」が ``list`` ではない場合に、引数の要素を指定します。

en: Argument_spec defines elements different than documentation does
ja: argument_spec はドキュメントとは異なるタイプを定義します。

en: Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``)
ja: ドキュメントではタイプをしていませんが、``argument_spec`` の引数がデフォルト型 (``str``) を使用しています。

en: argument in argument_spec is required but documentation says it is not, or vice versa
ja: arguments_spec の引数は必須ですが、ドキュメントには必須ではない (または arguments_spec の引数は必須ではありませんが、ドキュメントには必須) と記載されています。

en: Argument_spec defines type different than documentation does
ja: argument_spec がドキュメントとは異なるタイプを定義します。

en: Unknown ``DOCUMENTATION`` error
ja: 不明な ``DOCUMENTATION`` エラー

en: Invalid ``DOCUMENTATION`` schema
ja: 無効な ``DOCUMENTATION`` スキーマ

en: Imports
ja: インポート

en: Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``.
ja: ``absolute_import``、``division``、および ``print_function`` の ``from __future__`` インポートのみが許可されます。

en: Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``
ja: ドキュメント変数の前にインポートが見つかりました。すべてのインポートは、``DOCUMENTATION``/``EXAMPLES``/``RETURN`` の下に表示される必要があります。

en: ``Exception`` attempting to import module for ``argument_spec`` introspection
ja: ``Exception`` が、``argument_spec`` イントロスペクションのモジュールのインポートを試行中

en: Locations
ja: 場所

en: Warning
ja: 警告

en: Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``
ja: インポートは、``DOCUMENTATION``/``EXAMPLES``/``RETURN`` のすぐ後に配置しなければなりません。

en: Choices value from the argument_spec is not compatible with type defined in the argument_spec
ja: argument_spec の選択値は、argument_spec で定義されたタイプと互換性がありません

en: Default value from the argument_spec is not compatible with type defined in the argument_spec
ja: argument_spec のデフォルト値は、argument_spec で定義されたタイプと互換性がありません。

en: Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine
ja: argument_spec の引数は、Ansible Core Engine によって内部で使用されるため、「message」、「syslog_facility」のいずれかにすることはできません。

en: Argument in argument_spec must be a dictionary/hash when used
ja: argument_spec の引数を使用する場合は、ディクショナリーまたはハッシュである必要があります。

en: Suboptions in argument_spec are invalid
ja: argument_spec のサブオプションは無効です。

en: ``DOCUMENTATION`` is not valid YAML
ja: ``DOCUMENTATION`` は、有効な YAML ではありません

en: ``DOCUMENTATION.options`` must be a dictionary/hash when used
ja: ``DOCUMENTATION.options`` を使用する場合は、ディクショナリー/ハッシュでなければなりません

en: ``EXAMPLES`` is not valid YAML
ja: ``EXAMPLES`` は、有効な YAML ではありません

en: Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules
ja: 公式の Ansible モジュールでは、python モジュールの拡張子は ``.py`` で、powershell モジュールの拡張子は ``.ps1`` にする必要があります。

en: ``AnsibleModule`` schema validation error
ja: ``AnsibleModule`` スキーマ検証エラー

en: The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a semantic version, see https://semver.org/)
ja: 機能が削除されることになっているバージョンは解析できません (コレクションの場合、セマンティックバージョンである必要があります。https://semver.org/ を参照してください)。

en: Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1
ja: モジュール ``#AnsibleRequires -CSharpUtil`` の末尾を .cs にしないでください。モジュール ``#Requires`` の末尾を .psm1 にしないでください。

en: Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules)
ja: 最終行以外の ``main()`` の呼出し (または、非推奨およびドキュメントのみのモジュールでは ``removed_module()``)。

en: ``DOCUMENTATION`` fragment missing
ja: ``DOCUMENTATION`` フラグメントがありません

en: Pre-existing ``DOCUMENTATION`` fragment missing
ja: 既存の ``DOCUMENTATION`` フラグメントがありません

en: No ``DOCUMENTATION`` provided
ja: ``DOCUMENTATION`` が提供されていません

en: No ``EXAMPLES`` provided
ja: ``EXAMPLES`` が提供されていません

en: GPLv3 license header not found
ja: GPLv3 ライセンスヘッダーが見つかりませんでした

en: Next to last line is not ``if __name__ == "__main__":``
ja: 最後の行の隣になるものは、``if __name__ == "__main__":`` ではありません

en: Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules)
ja: ``main()`` への呼出しが見つかりませんでした (非推奨またはドキュメントのみのモジュールの場合は ``removed_module()``)。

en: Did not find ``ansible.module_utils.basic`` import
ja: ``ansible.module_utils.basic`` インポートが見つかりませんでした

en: No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found
ja: ``Ansible.ModuleUtils`` または C# Ansible ユーティリティーの 要件/インポートがあります

en: Interpreter line is not ``#!powershell``
ja: インタープリター行は ``#!powershell`` ではありません

en: Missing python documentation file
ja: python ドキュメントファイルがありません

en: Interpreter line is not ``#!/usr/bin/python``
ja: インタープリター行は ``#!/usr/bin/python`` ではありません

en: No ``RETURN`` documentation provided
ja: ``RETURN`` のドキュメントは提供されていません

en: No ``RETURN`` documentation provided for legacy module
ja: レガシーモジュールには ``RETURN`` のドキュメントがありません

en: Argument in argument_spec has sub-options but documentation does not define sub-options
ja: argument_spec の引数にはサブオプションョンがありますが、ドキュメントではサブオプションが定義されていません

en: Module level ``version_added`` is incorrect
ja: モジュールレベル ``version_added`` は正しくありません

en: Module level ``version_added`` is not a valid version number
ja: モジュールレベルの ``version_added`` は、有効なバージョン番号ではありません

en: ``module_utils`` imports should import specific components, not ``*``
ja: ``module_utils`` は、``*`` ではなく、特定のコンポーネントをインポートする必要があります

en: ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement
ja: ``Ansible.ModuleUtils`` 要件は、ステートメントごとに複数のモジュールをサポートしません。

en: Ansible C# util requirements do not support multiple utils per statement
ja: C# ユーティリティー要件は、ステートメントごとに複数のモジュールをサポートしません。

en: Option is marked as required but specifies a default. Arguments with a default should not be marked as required
ja: オプションは必須と識別されますが、デフォルトの引数を指定します。デフォルトの引数は必須と識別しないでください。

en: Parameters
ja: パラメーター

en: Option name suggests that the option contains a secret value, while ``no_log`` is not specified for this option in the argument spec. If this is a false positive, explicitly set ``no_log=False``
ja: オプション名は、オプションにシークレット値が含まれていることを示唆していますが、引数仕様ではこのオプションに対して ``no_log`` が指定されていません。このオプションが誤検出の場合は明示的に ``no_log=False`` に設定します。

en: Argument is listed in DOCUMENTATION.options, but not accepted by the module
ja: 引数は DOCUMENTATION.options に一覧表示されますが、モジュールでは受け入れられません。

en: ``version_added`` for new option is incorrect
ja: 新しいオプションの ``version_added`` は正しくありません

en: ``version_added`` for option is not a valid version number
ja: ``version_added`` オプションが有効なバージョン番号ではありません

en: Argument in argument_spec is not a valid python identifier
ja: argument_spec の引数は有効な python 識別子ではありません

en: Value for "elements" is valid only when value of "type" is ``list``
ja: 「elements」の値は、「type」の値が ``list`` である場合に限り有効です

en: Argument_spec implies ``type="str"`` but documentation defines it as different data type
ja: argument_spec には ``type="str"`` の意が含まれますが、ドキュメントでは、別のデータ型として指定されています

en: Type value is defined in ``argument_spec`` but documentation doesn't specify a type
ja: タイプ値は ``argument_spec`` で定義されていますが、ドキュメントはタイプを指定していません

en: argument in argument_spec has at least one alias specified multiple times in aliases
ja: argument_spec の引数には、エイリアスに複数回指定されたエイリアスが 1 つ以上含まれます

en: argument in argument_spec is specified as its own alias
ja: argument_spec の引数は、独自のエイリアスとして指定されます

en: argument in argument_spec with aliases is documented multiple times
ja: エイリアスを持つ argument_spec の引数が複数回文書化されています

en: argument in argument_spec "type" is specified as ``list`` without defining "elements"
ja: argument_spec「type」の引数は、「要素」を定義せずに ``list`` のように指定されます。

en: Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice.  Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module.
ja: 引数 ``state`` には、``get``、``list``、または ``info`` が含まれています。機能性は ``_info`` または (追加の条件が適用される場合は) ``_facts`` モジュールである必要があります。

en: Python ``SyntaxError`` while parsing module
ja: モジュールの解析中の Python ``SyntaxError``

en: According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0)
ja: セマンティックバージョニング仕様 (https://semver.org/)) によると、機能の削除が許可されているバージョンはメジャーバージョン (x.0.0) のみです。

en: ``RETURN`` is not valid YAML, ``RETURN`` fragments missing  or invalid
ja: ``RETURN`` は、有効な YAML ではありません。``RETURN`` フラグメントが見つからないか、無効です。

en: ``version_added`` for return value is not a valid version number
ja: 戻り値の ``version_added`` は、有効なバージョン番号ではありません

en: Ansible module subdirectories must contain an ``__init__.py``
ja: Ansible モジュールのサブディレクトリーには ``__init__.py`` が含まれている必要があります。

en: Try/Except ``HAS_`` expression missing
ja: try/Except ``HAS_`` 式がない

en: Argument is listed in the argument_spec, but not documented in the module
ja: 引数が argument_spec に記載されていますが、このモジュールでは文書化されていません。

en: Type comparison using ``type()`` found. Use ``isinstance()`` instead
ja: ``type()`` を使用したタイプ比較。代わりに ``isinstance()`` を使用してください。

en: Unknown pre-existing ``DOCUMENTATION`` error
ja: 不明な既存の ``DOCUMENTATION`` エラー

en: ``boto`` import found, new modules should use ``boto3``
ja: ``boto`` インポートが見つかりました。代わりに ``boto3`` を使用してください

en: ``sys.exit()`` call found. Should be ``exit_json``/``fail_json``
ja: ``sys.exit()`` 呼び出しが見つかりました。``exit_json``/``fail_json`` でなければなりません。

en: ``requests`` import found, should use ``ansible.module_utils.urls`` instead
ja: ``requests`` インポートしています。代わりに ``ansible.module_utils.urls`` を使用してください

en: ``os.call`` used instead of ``module.run_command``
ja: ``module.run_command`` の代わりに、``os.call`` を使用します。

en: ``subprocess.Popen`` used instead of ``module.run_command``
ja: ``module.run_command`` の代わりに、``subprocess.Popen`` を使用します。

en: GPLv3 license header should be the :ref:`short form <copyright>` for new modules
ja: GPLv3 ライセンスヘッダーは、新しいモジュールの :ref:`短縮形 <copyright>` である必要があります

en: mutually_exclusive entry contains non-string value
ja: mutually_exclusive エントリーには文字列以外の値が含まれます

en: mutually_exclusive entry has repeated terms
ja: mutually_exclusive エントリーが繰り返し使用されます

en: mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?)
ja: mutually_exclusive エントリーには、argument_spec に表示されないオプションが含まれています (オプションのエイリアスである可能性がありますか?)

en: required_one_of entry contains non-string value
ja: required_one_of エントリーには文字列以外の値が含まれます

en: required_one_of entry has repeated terms
ja: required_one_of エントリーが繰り返し使用されます

en: required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?)
ja: required_one_of エントリーには、argument_spec に表示されないオプションが含まれています (オプションのエイリアスである可能性がありますか?)

en: required_together entry contains non-string value
ja: required_together エントリーには文字列以外の値が含まれます

en: required_together entry has repeated terms
ja: required_together エントリーが繰り返し使用されます

en: required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?)
ja: required_together エントリーには、argument_spec に表示されないオプションが含まれています (オプションのエイリアスである可能性がありますか?)

en: required_if entry has a fourth value which is not a bool
ja: required_if エントリーには bool ではない 4 つ目の値がある

en: required_if entry has a third value (requirements) which is not a list or tuple
ja: required_if エントリーには、リストまたはタプルではない 3 つの値 (必須) があります。

en: required_if entry has repeated terms in requirements
ja: required_if エントリーが繰り返し使用されます

en: required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?)
ja: required_if エントリーの要件には、argument_spec に表示されないオプションが含まれています (オプションのエイリアスである可能性がありますか?)

en: required_if entry's key does not appear in argument_spec (potentially an alias of an option?)
ja: required_if エントリーのキーが argument_spec に表示されません (オプションのエイリアスである可能性がありますか?)

en: required_if entry contains its key in requirements list/tuple
ja: required_if エントリーには要件リスト/タプルのキーが含まれます

en: required_if entry's value is not of the type specified for its key
ja: required_if エントリーの値は、キーに指定されたタイプではありません

en: required_by entry has repeated terms
ja: required_by エントリーが繰り返し使用されます

en: required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?)
ja: required_by エントリーには、argument_spec に表示されないオプションが含まれます (オプションのエイリアスである可能性がありますか?)

en: According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0)
ja: セマンティックバージョニング仕様 (https://semver.org/)) によると、機能の追加が許可されているバージョンはメジャーバージョンおよびマイナーバージョン (x.y.0) のみです
