Skip to content

Commit

Permalink
Merge pull request cakephp#2909 from okinaka/update-documentation
Browse files Browse the repository at this point in the history 
[ja] update documentation.rst
  • Loading branch information
@markstory
markstory committed Jun 27, 2015
2 parents 79020b3 + 163ed19 commit 35c34bc
Showing 1 changed file with 153 additions and 41 deletions.
194 changes: 153 additions & 41 deletions ja/contributing/documentation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,84 @@
ドキュメントへの貢献の方法はシンプルです。
ファイルは https://github.com/cakephp/docs にホストされています。
自由にレポジトリをフォークして、変更・改善・翻訳を追加し、プルリクエストを発行してください。
またファイルをダウンロードせず、GitHubを使ってオンラインでドキュメントを編集することもできます。
またファイルをダウンロードせず、ページにある "Improve this Doc" ボタンから GitHub の
オンラインエディタを使って直接ドキュメントを編集することもできます。

CakePHP のドキュメントは、
`継続的に統合 <http://en.wikipedia.org/wiki/Continuous_integration>`_
されます。また、 Jenkins サーバ上で、いつでも `様々なビルド <http://ci.cakephp.org>`_ の
ステータスを確認できます。

翻訳
====

ドキュメントチーム(*docs at cakephp dot org*)までEメールを送るか、IRC (#cakephp on freenode)で、参加したい旨を連絡してください。
ドキュメントチーム (*docs at cakephp dot org*) までEメールを送るか、IRC
(#cakephp on freenode) で、参加したい旨を連絡してください。

新しい言語の翻訳
------------------

私たちは、できる限り完全な翻訳を提供したいです。しかしながら、翻訳ファイルが最新ではない場合が
あるかもしれません。英語版ドキュメントを信頼できるバージョンとして考えてください。

もし、あなたの言語の翻訳がない場合、 Github を通して連絡してください。そして、私たちは
スケルトンフォルダを作成することを考えるでしょう。以下のセクションは、頻繁に更新されることは
ありませんので、初めに翻訳することを考えてください:

- index.rst
- cakephp-overview.rst
- getting-started.rst
- installation.rst
- /installation フォルダ
- /getting-started フォルダ
- /tutorials-and-examples フォルダ

ドキュメント管理者の備忘録
---------------------------

全ての言語のフォルダーの構造は、英語のフォルダに合わせるべきです。もし、英語版で構造が変わったら、
他の言語にもそれらの変更を適用すべきです。

例えば、 **en/file.rst** に新しい英語のファイルが作られた場合:

..
- Add the file in all other languages : **fr/file.rst**, **zh/file.rst**, ...
- Delete the content, but keeping the ``title``, ``meta`` information and
eventual ``toc-tree`` elements. The following note will be added while nobody
has translated the file::
- 他の全ての言語のファイルを追加します : **fr/file.rst**, **zh/file.rst**, ...
- ``title`` と ``meta`` 情報と最後に ``toc-tree`` 要素を保ったままで、内容を削除します。
誰かがファイルを翻訳するまでは、以下の注意書きが追加されます::

File Title
##########

.. note::
The documentation is not currently supported in XX language for this
page.

Please feel free to send us a pull request on
`Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
button to directly propose your changes.

You can refer to the English version in the select top menu to have
information about this page's topic.

翻訳者tips:
// toc-tree 要素が英語版にある場合
.. toctree::
:maxdepth: 1

one-toc-file
other-toc-file

.. meta::
:title lang=xx: File Title
:keywords lang=xx: title, description,...


翻訳者 tips
------------

- 翻訳する言語のページで閲覧・編集してください。
そうしないと、どこが既に翻訳されているかわからないでしょう。
Expand All @@ -27,35 +97,39 @@
- アクセント文字のために
`HTML エンティティ <http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references>`_
を使用しないでください。
この本はUTF-8を使っています。
- 記述(HTML)の変更や新しいコンテンツを、一度にたくさん加えないでください。
この本は UTF-8 を使っています。
- 記述 (HTML) の変更や新しいコンテンツを、一度にたくさん加えないでください。
- 元のコンテンツに不備がある場合は、まずそれを編集するようにしてください。

ドキュメントのフォーマットガイド
================================

新しいCakePHPのドキュメントはReSTフォーマットテキストで書かれています。
ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキストのマークアップ記法です。
一貫性を保持するために、CakePHPドキュメントに追加をする場合、以下のテキストのフォーマットと構造化をする方法のガイドラインに従うことが推奨されます。
新しい CakePHP のドキュメントは
`ReST フォーマットテキスト <http://en.wikipedia.org/wiki/ReStructuredText>`_
で書かれています。
ReST (Re Structured Text) は markdown や textile と同様のプレーンテキストの
マークアップ記法です。一貫性を保持するために、CakePHP ドキュメントに追加をする場合、
以下のテキストのフォーマットと構造化をする方法のガイドラインに従うことが推奨されます。

行の長さ
--------

テキストの行は80列でワードラップがかけられるべきです。
例外は長いURLとコードスニペットのみです。
テキストの行は 80 列でワードラップがかけられるべきです。
例外は長い URL とコードスニペットのみです。

見出しとセクション
------------------

セクションの見出しはテキストの長さ以上の区切り文字でタイトルにアンダーラインをつけることで作成されます。
セクションの見出しはテキストの長さ以上の区切り文字でタイトルにアンダーラインをつけることで
作成されます。

- ``#`` はページタイトルを意味するのに使われます。
- ``=`` はページのセクションを意味するのに使われます。
- ``-`` はサブセクションを意味するのに使われます。
- ``~`` はサブ-サブセクションを意味するのに使われます。
- ``^`` はサブ-サブ-サブセクションを意味するのに使われます。

見出しは5レベルより深くネストしてはなりません。
見出しは 5 レベルより深くネストしてはなりません。
また、空行で囲まれる必要があります。

段落(*Paragraphs*)
Expand All @@ -67,29 +141,45 @@ ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキス
インラインマークアップ
----------------------

* 単一のアスタリスク: *text* 強調(斜体)、
* 二つのアスタリスク: **text** 強い強調(太文字)、
* 単一のアスタリスク: *text* 強調(斜体)。
一般的なハイライト/強調のために使用します。

* ``*text*``.

* 二つのアスタリスク: **text** 強い強調(太文字)。
ワークディレクトリ、箇条書きの項目、テーブル名、「テーブル」という言葉を省略するために
使用します。

* ``**/config/Migrations**``, ``**articles**``, etc.

* バッククォート: ``text`` コード例。
メソッドオプション名、テーブルカラム名、オブジェクト名、「オブジェクト」という言葉を
省略するため、"()"をつけてメソッド/関数名に使用します。

* ````cascadeCallbacks````, ````true````, ````id````,
````PagesController````, ````config()````, etc.

もしアスタリスクやバッククォートがテキストが書かれている中に現れ、インラインマークアップの区切り文字に取り間違えられることがあるなら、バックスラッシュでエスケープする必要があります。
もしアスタリスクやバッククォートがテキストが書かれている中に現れ、インラインマークアップの
区切り文字に取り間違えられることがあるなら、バックスラッシュでエスケープする必要があります。

インラインマークアップは多少の制限があります:

* ネスト **できない場合があります** 。
* 中身は空白で開始・終了できないでしょう: ``* text*`` は間違いです。
* 中身は非単語文字で、周囲のテキストから分離されている必要があります。
これを回避するためにバックスラッシュでエスケープされた空白を使ってください: ``一つの長い\ *太文字*\ 単語`` 。
これを回避するためにバックスラッシュでエスケープされた空白を使ってください:
``一つの長い\ *太文字*\ 単語`` 。

リスト
------

リストマークアップはmarkdownに非常によく似ています。
リストマークアップは markdown に非常によく似ています。
順番なしのリストは単一のアスタリスクと空白から始まる行によって示されます。
順番がついたリストは同様に数字、または ``#`` で自動的なナンバリングがなされます::

* これは中黒(*bullet*)です
* これは中黒 (*bullet*) です
* これも同じです。しかしこの行は
2行あります。
2 行あります。

1. 一番目の行
2. 二番目の行
Expand All @@ -109,12 +199,13 @@ ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキス

定義リストは以下のようにして作成できます::

項目
用語
定義
CakePHP
PHPのMVCフレームワーク
PHP の MVC フレームワーク

項目は1行以上にすることができませんが、定義は複数行にすることができ、全ての行は一貫したインデントをつける必要があります。
用語は 1 行以上にすることができませんが、定義は複数行にすることができ、全ての行は
一貫したインデントをつける必要があります。

リンク
------
Expand All @@ -128,18 +219,20 @@ ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキス

`外部リンク <http://example.com>`_

以上のものはhttp://example.comに向けてのリンクを生成します。
以上のものは http://example.com に向けてのリンクを生成します。

他のページへのリンク
~~~~~~~~~~~~~~~~~~~~

.. rst:role:: doc
ドキュメントの他のページへ ``:doc:`` ロール(*role*)を使ってリンクします。
ドキュメントの他のページへ ``:doc:`` ロール (*role*) を使ってリンクします。
指定するドキュメントへ絶対パスまたは相対パス参照を用いてリンクできます。
``.rst`` 拡張子は省く必要があります。
例えば、 ``:doc:`form``` が ``core-helpers/html`` に現れたとすると、リンクは ``core-helpers/form`` を参照します。
もし参照が ``:doc:`/core-helpers``` であったら、どこで使われるかを厭わずに、常に ``/core-helpers`` を参照します。
例えば、 ``:doc:`form``` が ``core-helpers/html`` に現れたとすると、
リンクは ``core-helpers/form`` を参照します。
もし参照が ``:doc:`/core-helpers``` であったら、どこで使われるかに関わらず、
常に ``/core-helpers`` を参照します。

相互参照リンク
~~~~~~~~~~~~~~
Expand All @@ -148,7 +241,8 @@ ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキス
``:ref:`` ロールを使って任意のドキュメントに任意のタイトルを相互参照することができます。
リンクのラベルはドキュメント全体に渡って一意のものに向けられる必要があります。
クラスのメソッドのラベルを作る時は、リンクのラベルのフォーマットとして ``class-method`` を使うのがベストです。
クラスのメソッドのラベルを作る時は、リンクのラベルのフォーマットとして ``class-method`` を
使うのがベストです。

ラベルの最も一般的な使い方は上記のタイトルです。例::

Expand All @@ -160,16 +254,17 @@ ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキス
続きの内容..

他の場所で、 ``:ref:`ラベル名``` を用いて上記のセクションを参照することができます。
リンクのテキストはリンクの先にあるタイトルになります。
また、 ``:ref:`リンクテキスト <ラベル名>``` として自由にリンクのテキストを指定することができます。
リンクのテキストはリンクの先にあるタイトルになります。また、
``:ref:`リンクテキスト <ラベル名>``` として自由にリンクのテキストを指定することができます。

クラスとその内容を記述する
--------------------------

CakePHPのドキュメントは `phpdomain
CakePHP のドキュメントは `phpdomain
<http://pypi.python.org/pypi/sphinxcontrib-phpdomain>`_
を用いてPHPのオブジェクトと構成物を記述するための独自のディレクティブを提供します。
適切な索引(*index*)と相互参照機能を与えるためにこのディレクティブとロールを必ず使う必要があります。
を用いて PHP のオブジェクトと構成物を記述するための独自のディレクティブを提供します。
適切な索引 (*index*) と相互参照機能を与えるためにこのディレクティブとロールを必ず使う
必要があります。

クラスと構成物を記述する
------------------------
Expand All @@ -178,7 +273,7 @@ CakePHPのドキュメントは `phpdomain

.. rst:directive:: .. php:global:: name
このディレクティブは新規のPHPのグローバル変数を定義します。
このディレクティブは新規の PHP のグローバル変数を定義します。

.. rst:directive:: .. php:function:: name(signature)
Expand All @@ -187,11 +282,11 @@ CakePHPのドキュメントは `phpdomain
.. rst:directive:: .. php:const:: name
このディレクティブは新規の定数を定義します。
これをclassディレクティブの中でネストして使うことにより、クラス定数を作成することもできます。
これを class ディレクティブの中でネストして使うことにより、クラス定数を作成することもできます。

.. rst:directive:: .. php:exception:: name
このディレクティブは現在の名前空間内で新規の例外(*Exception*)を定義します。
このディレクティブは現在の名前空間内で新規の例外 (*Exception*) を定義します。
コンストラクタの引数を含める書き方もできます。

.. rst:directive:: .. php:class:: name
Expand Down Expand Up @@ -247,7 +342,7 @@ CakePHPのドキュメントは `phpdomain
相互参照
~~~~~~~~

以下のロールはPHPのオブジェクトを参照し、適合するディレクティブがあればリンクが生成されます:
以下のロールは PHP のオブジェクトを参照し、適合するディレクティブがあればリンクが生成されます:

.. rst:role:: php:func
Expand Down Expand Up @@ -310,15 +405,19 @@ CakePHPのドキュメントは `phpdomain
----------

重要なヒント、特別な注記、潜在的な危険を読者に知らせるためにしたいことがしばしばあります。
sphinxの警告(*Admonitions*)は、まさにそのために使われます。
警告には3つの種類があります。
sphinx の警告 (*Admonitions*) は、まさにそのために使われます。
警告には 5 つの種類があります。

* ``.. tip::`` tipは面白い情報や重要な情報を文書化、または再反復するために使用されています。
* ``.. tip::`` tip は面白い情報や重要な情報を文書化、または再反復するために使用されています。
ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
* ``.. note::`` noteは情報の特に重要なもののひとつを文書化するために使用されています。
* ``.. note::`` note は情報の特に重要なもののひとつを文書化するために使用されています。
ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
* ``.. warning::`` warningは潜在的な障害、またはセキュリティに関する情報を文書化するために使用されています。
* ``.. warning::`` warning は潜在的な障害、またはセキュリティに関する情報を文書化するために使用されています。
ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
* ``.. versionadded:: X.Y.Z`` "version added" 警告は、上記の機能が
``X.Y.Z`` バージョンで追加された新しい機能であることを示すために使用されます。
* ``.. deprecated:: X.Y.Z`` "version added" 警告の反対で、"deprecated" 警告は、
``X.Y.Z`` バージョンから非推奨になった機能の告知のために使用されます。

全ての警告は同じようになります::

Expand All @@ -343,3 +442,16 @@ sphinxの警告(*Admonitions*)は、まさにそのために使われます。
.. warning::

危険に晒されるかもしれません。

.. versionadded:: 2.6.3

バージョン 2.6.3 で素晴らしい機能が追加されました。

.. deprecated:: 2.6.3

バージョン 2.6.3 で古い機能は非推奨になりました。


.. meta::
:title lang=ja: Documentation
:keywords lang=ja: partial translations,translation efforts,html entities,text markup,asfd,asdf,structured text,english content,markdown,formatted text,dot org,repo,consistency,translator,freenode,textile,improvements,syntax,cakephp,submission

0 comments on commit 35c34bc

Please sign in to comment.