20 Grailsに貢献する - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith
Version: 2.3.0
Translated by: T.Yamamoto, Japanese Grails Doc Translating Team. Special thanks to NTT Software.
【注意】このドキュメントの内容はスナップショットバージョンを元に*意訳*されているため、一部現行バージョンでは未対応の機能もあります。
Table of Contents
20 Grailsに貢献する
Grails is an open source project with an active community and we rely heavily on that community to help make Grails better. As such, there are various ways in which people can contribute to Grails. One of these is by writing useful plugins and making them publicly available. In this chapter, we'll look at some fo the other options.
Grailsはオープンソースプロジェクトにより開発が進められており、Grailsをより良くしようとする活発なコミュニティ活動がその多くを支えています。
そのため、Grails開発に貢献するための様々な手段が用意されています。
その1つの手段が有益なプラグインを作成し世の中で使ってもらうことです。
この章では、それ以外にどんな貢献ができるのかを見ていきます。
20.1 JIRAで課題を報告する（バグ報告）
Grails uses JIRA to track issues in the core framework, its documentation, its website, and many of the public plugins. If you've found a bug or wish to see a particular feature added, this is the place to start. You'll need to create a (free) JIRA account in order to either submit an issue or comment on an existing one.
Grails開発では、コアフレームワークやドキュメント、ウェブサイトや多くの公開プラグインの課題管理にJIRAを利用しています。
バグを見つけたり、追加機能の要望がある場合には、ここで課題を作成します。
課題を新規に作成したり、既存の課題にコメントしたりするには、JIRAの無料のアカウントが必要です。When submitting issues, please provide as much information as possible and in the case of bugs, make sure you explain which versions of Grails and various plugins you are using. Also, an issue is much more likely to be dealt with if you attach a reproducible sample application (which can be packaged up using the
課題を作成する場合には、できるだけ多くの情報を記述するようにしてください。
バグの場合、利用しているGrailsのバージョンやプラグインが説明されているか確認してください。
また、事象が再現可能なサンプルアプリケーションを添付すると課題への対応がやりやすくなります。
（grails bug-report command).grails bug-reportコマンドを使ってアプリケーションをパッケージングできます。）h3. Reviewing issues
課題をレビューする
There are quite a few old issues in JIRA, some of which may no longer be valid. The core team can't track down these alone, so a very simple contribution that you can make is to verify one or two issues occasionally.
JIRAの中には古い課題がかなりの数存在し、その中には既に調べる意味がないものも含まれています。
コアチームだけでこれだけ多くのものを解決に導くことはできません。
というわけで、あなたが実施できるとてもシンプルな貢献は、ときどき課題の1つか2つを検証することです。Which issues need verification? A shared JIRA filter will display all issues that haven't been resolved and haven't been reviewed by someone else in the last 6 months. Just pick one or two of them and check whether they are still relevant.
では、どの課題を検証すればよいのでしょうか？
共有のJIRAフィルタにより、未解決のまま過去6ヶ月間誰も見直ししていない課題がすべて表示されます。
このうちから1つか2つを選んで、それが今でも対応する価値があるかどうかを調べてください。Once you've verified an issue, simply edit it and set the "Last Reviewed" field to today. If you think the issue can be closed, then also check the "Flagged" field and add a short comment explaining why. Once those changes are saved, the issue will disappear from the results of the above filter. If you've flagged it, the core team will review and close if it really is no longer relevant.
課題が検証できたら、その課題を単に編集して「Last Reviewed」フィールドを今日の日付に更新してください。
もしその課題をクローズしてもよいと考えるなら、「Flagged」フィールドにもチェックを付けて、その理由を短いコメントとして追加してください。
変更を保存すれば、この課題は上記のフィルタの表示結果から消えます。
あなたがフラグをつけた課題は、コアチームがレビューして、本当にもう価値がない場合は課題をクローズします。One last thing: you can easily set the above filter as a favourite on this JIRA screen so that it appears in the "Issues" drop down. Just click on the star next to a filter to make it a favourite.
最後にもうひとつ:
このJIRAの画面
で上記のフィルタを簡単にお気に入りとしてセットできます。
こうするとメニューバーの「Issues」ドロップダウンリストにこのフィルタが表示されるようになります。
お気に入りにするには、フィルタの隣にある星印をクリックするだけです。
20.2 ソースからビルドしてテストを実行する
If you're interested in contributing fixes and features to the core framework, you will have to learn how to get hold of the project's source, build it and test it with your own applications. Before you start, make sure you have:
もしバグフィックスやコアフレームワークへの機能追加に興味があるなら、プロジェクトのソースコードを手に入れ、ビルドし、それを自分で作ったアプリケーションでテストする方法を身につけることが必要です。
まずはじめに、以下がインストールされていることを確認してください:- A JDK (1.6 or above)
- A git client
- JDK (1.6以降)
- gitクライアント
Once you have all the pre-requisite packages installed, the next step is to download the Grails source code, which is hosted at GitHub in several repositories owned by the "grails" GitHub user. This is a simple case of cloning the repository you're interested in. For example, to getthe core framework run:
必要なパッケージをすべてインストールしたら、次にGrailsのソースコードをダウンロードします。
ソースコードは、GitHub上のgrailsユーザーが所有するいくつかのリポジトリにホストされています。
これは欲しいリポジトリをクローンする簡単な例です。
たとえば、コアフレームワークを取得するには、以下を実行します:git clone http://github.com/grails/grails-core.git
This will create a "grails-core" directory in your current working directory containing all the project source files. The next step is to get a Grails installation from the source.
これにより現在の作業ディレクトリに、プロジェクトのすべてのソースコードを含む「grails-core」ディレクトリが作成されます。
次のステップでは、このソースからGrailsの一式を入手します。h3. Creating a Grails installation
Grails一式を作成する
If you look at the project structure, you'll see that it doesn't look much like a standard
このプロジェクト構造をみると、標準のGRAILS_HOME installation. But, it's very simple to turn it into one. Just run this from the root directory of the project:GRAILS_HOMEとはあまり似ていないことに気づくでしょう。
しかし、これを標準的なものに変換するのはとても簡単です。
プロジェクトのルートディレクトリで以下のコマンドを実行します:./gradlew install
This will fetch all the standard dependencies required by Grails and then build a
これによりGrailsが必要とする標準的な依存関係がすべて解決され、GRAILS_HOME installation. Note that this target skips the extensive collection of Grails test classes, which can take some time to complete.GRAILS_HOMEの一式がビルドされます。
このコマンドでは、完了に時間がかかるGrailsの大量のテストクラスはスキップされることに注意してください。Once the above command has finished, simply set the
上記のコマンドが完了したら、GRAILS_HOME environment variable to the checkout directory and add the "bin" directory to your path. When you next type run the grails command, you'll be using the version you just built.GRAILS_HOME環境変数を今回チェックアウトしたディレクトリにセットし、「bin」ディレクトリにパスを通してください。
これで次にgrailsコマンドを実行したときには、自分でビルドしたバージョンが使われるようになります。h3. Running the test suite
テストスイートを実行する
All you have to do to run the full suite of tests is:
すべてのテストスイートを実行するには、以下のコマンドを実行します:./gradlew test
These will take a while (15-30 mins), so consider running individual tests using the command line. For example, to run the test case
すべてのテストを実行するにはかなりの時間（15-30分）がかかります。
そのため、コマンドラインから個別にテストを指定して実行することを検討してください。
たとえば、MappingDslTests simply execute the following command:MappingDslTestsというテストケースを実行するには、単純に以下のコマンドを実行します:./gradlew -Dtest.single=MappingDslTest :grails-test-suite-persistence:test
Note that you need to specify the sub-project that the test case resides in, because the top-level "test" target won't work....
トップレベルの「test」ターゲットではうまく動かないため、対象のテストケースが存在するサブプロジェクトを指定する必要があることに注意してください。h3. Developing in IntelliJ IDEA
IntelliJ IDEAで開発する
You need to run the following gradle task:
次のGradleタスクを実行する必要があります:./gradlew idea
Then open the project file which is generated in IDEA. Simple!
次に、生成したプロジェクトファイルをIDEAで開いてください。
簡単ですね！h3. Developing in STS / Eclipse
STS/Eclipseで開発する
You need to run the following gradle task:
次のGradleタスクを実行する必要があります:./gradlew cleanEclipse eclipse
Before importing projects to STS do the following action:
STSにプロジェクトをインポートする前に、以下の作業を実施してください:* Edit grails-scripts/.classpath and remove the line "<classpathentry kind="src" path="../scripts"/>".
grails-scripts/.classpathを編集して、<classpathentry kind="src" path="../scripts"/>の行を削除します。
Use "Import->General->Existing Projects into Workspace" to import all projects to STS. There will be a few build errors. To fix them do the following:
メニューの「Import -> General -> Existing Projects into Workspace」から、すべてのプロジェクトをSTSにインポートします。
いくつかのビルドエラーが出ますが、エラーを解消するため以下の手順を実施してください:- Add the springloaded-core JAR file in $GRAILS_HOME/lib/com.springsource.springloaded/springloaded-core/jars to grails-core's classpath.
- Remove "src/test/groovy" from grails-plugin-testing's source path GRECLIPSE-1067
- Add the jsp-api JAR file in $GRAILS_HOME/lib/javax.servlet.jsp/jsp-api/jars to the classpath of grails-web
- Fix the source path of grails-scripts. Add linked source folder linking to "../scripts". If you get build errors in grails-scripts, do "../gradlew cleanEclipse eclipse" in that directory and edit the .classpath file again (remove the line "<classpathentry kind="src" path="../scripts"/>"). Remove possible empty "scripts" directory under grails-scripts if you are not able to add the linked folder.
- Do a clean build for the whole workspace.
- To use Eclipse GIT scm team provider: Select all projects (except "Servers") in the navigation and right click -> Team -> Share project (not "Share projects"). Choose "Git". Then check "Use or create repository in parent folder of project" and click "Finish".
- Get the recommended code style settings from the mailing list thread (final style not decided yet, currently profile.xml). Import the code style xml file to STS in Window->Preferences->Java->Code Style->Formatter->Import . Grails code uses spaces instead of tabs for indenting.
$GRAILS_HOME/lib/com.springsource.springloaded/springloaded-core/jarsにあるspringloaded-coreのJARファイルをgrails-coreのクラスパスに追加します。- grails-plugin-testingのソースパスから
src/test/groovyを削除します(GRECLIPSE-1067)。 $GRAILS_HOME/lib/javax.servlet.jsp/jsp-api/jarsにあるjsp-apiのJARファイルをgrails-webのクラスパスに追加します。- grails-scriptsのソースパスを修正します。
../scriptsにリンクされたソースの「linked folder」を追加します。もしgrails-scriptsでビルドエラーが出るようなら、grails-scriptsディレクトリで../gradlew cleanEclipse eclipseを実行し、.classpathファイルを再度編集します（<classpathentry kind="src" path="../scripts"/>という行を削除します）。「linked folder」を追加できない場合、grails-scriptsにある（おそらく空である）scriptsディレクトリを削除します。 - ワークスペース全体に対しクリーンビルドを実行します。
- 「Eclipse GIT scm team provider」を利用する場合は、ナビゲーションビューで「Servers」以外のすべてのプロジェクトを選択し、右クリックから「Team -> Share project」(複数形ではありませんが)を実行します。「Git」を選び、「Use or create repository in parent folder of project」にチェックを入れ、「Finish」をクリックします。
- 推奨されるコードスタイルの設定はメーリングリストのスレッドから入手してください。（最終的なスタイルはまだ確定されていません。現状版はprofile.xmlです。）メニューの「Window -> Preferences -> Java -> Code Style -> Formatter -> Import」から、コードスタイルのXMLファイルをSTSにインポートします。Grailsコードでは、インデントにはタブではなくスペースを使用します。
h3. Debugging Grails or a Grails application
GrailsやGrailsアプリケーションをデバッグする
To enable debugging, run:
デバッグモードを有効にするには、以下のように実行します:grails -debug <command>
and then connect to the JVM remotely via the IDE ("remote debugging") using the port 5005. Of course, if you have modified the
そして、IDEのリモートデバッグで、5005ポートを使ってそのJVMにリモート接続します。
もちろん、 startGrails script to use a different port number, connect using that one.startGrailsスクリプトを修正して別のポート番号を使うようにしていた場合、その番号を使ってください。In previous versions of Grails there was a以前のバージョンのGrailsにはgrails-debugcommand. The command is still included in the distribution and is deprecated in favor of the-debugswitch to the standardgrailscommand.grails-debugコマンドがありました。 このコマンドはまだディストリビューションに含まれていますが、将来は廃止予定です。 標準のgrailsコマンドに対する-debugスイッチが推奨されています。
If you need to debug stuff that happens during application startup, then you should modify the "grails-debug" script and change the "suspend" option from 'n' to 'y'. You can read more about the JPDA connection settings TODO here: http://java.sun.com/j2se/1.5.0/docs/guide/jpda/conninv.html#Invocation.
もしアプリケーション起動時に起こる事象をデバッグしたい場合は、grails-debugスクリプトを修正し、suspendオプションをnからyに変更します。
なお、JPDA(Java Platform Debugger Architecture)の接続設定については、http://java.sun.com/j2se/1.5.0/docs/guide/jpda/conninv.html#Invocationでより詳細を知ることができます。It's also possible to get Eclipse to wait for incoming debugger connections and instead of using "-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005" you could use this "-Xrunjdwp:transport=dt_socket,server=n,address=8000" (which assumes the Eclipse default port for remote java applications) Inside eclipse you create a new "Remote Java Application" launch configuration and change the connection type to "Standard (Socket Listen)" and click debug. This allows you to start a debugger session in eclipse and just leave it running and you're free to debug anything without having to keep remembering to relaunch a "Socket Attach" launch configuration. You might find it handy to have 2 scripts, one called "grails-debug", and another called "grails-debug-attach"
また、Eclipseにデバッグ用の接続が来るのを待ち受けさせることもできます。
その場合、-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005の代わりに、-Xrunjdwp:transport=dt_socket,server=n,address=8000が必要です。
（これはEclipseのリモートJavaアプリケーションに対するデフォルトポートを想定しています。）
Eclipseで新規に「Remote Java Application」を実行し、接続タイプを「Standard (Socket Listen)」として、「Debug」をクリックします。
これにより、Eclipseでデバッグセッションを起動したままにできるので、「Socket Attach」の再実行を忘れないように気を遣わずとも、自由にデバッグできます。
この場合、grails-debugとgrails-debug-attachという2つのスクリプトが便利に使えます。
20.3 Grailsコアにパッチを送る
If you want to submit patches to the project, you simply need to fork the repository on GitHub rather than clone it directly. Then you will commit your changes to your fork and send a pull request for a core team member to review.
もしプロジェクトにパッチを送りたいなら、GitHubのリポジトリを直接クローンするのではなく、フォークする必要があります。
それから変更を自分のフォークにコミットして、コアチームのメンバーがレビューできるようにプルリクエストを送ります。h3. Forking and Pull Requests
フォークとプルリクエスト
One of the benefits of GitHub is the way that you can easily contribute to a project by forking the repository and sending pull requests with your changes.
GitHubを利用するメリットの1つはプロジェクトへの貢献が容易になることです。
リポジトリをフォークして、自分の加えた変更に対するプルリクエストを送ればよいからです。What follows are some guidelines to help ensure that your pull requests are speedily dealt with and provide the information we need. They will also make your life easier!
以下に挙げるのはガイドラインであり、あなたのプルリクエストが素早く処理されるように手助けし、我々に必要な情報を提供してくれます。
あなたの作業も楽になるでしょう！h4. Create a local branch for your changes
変更用ローカルブランチを作成する
Your life will be greatly simplified if you create a local branch to make your changes on. For example, as soon as you fork a repository and clone the fork locally, execute
変更を行っていくためのローカルブランチを作ることで、作業も大幅にシンプルになります。
たとえば、リポジトリをフォークして、そのフォークをローカルにクローンしたら、以下を実行します:git checkout -b mine
This will create a new local branch called "mine" based off the "master" branch. Of course, you can name the branch whatever you like - you don't have to use "mine".
これでmasterブランチからmineという名前の新しいローカルブランチが作られます。
もちろん、ブランチの名前は好きなように付けてください。
mineという名前を使う必要はありません。h4. Create JIRAs for non-trivial changes
重要な変更についてはJIRAで課題を作成する
For any non-trivial changes, raise a JIRA issue if one doesn't already exist. That helps us keep track of what changes go into each new version of Grails.
重要な変更については、まだ存在していなければ、JIRAで新たに課題を作成してください。
それにより、新しいバージョンのGrailsにどのような変更が入ったか追いかけやすくなるからです。h4. Include JIRA issue ID in commit messages
コミットログにJIRAの課題IDを含める
This may not seem particularly important, but having a JIRA issue ID in a commit message means that we can find out at a later date why a change was made. Include the ID in any and all commits that relate to that issue. If a commit isn't related to an issue, then there's no need to include an issue ID.
これはあまり重要ではないと思われるかもしれません。
しかし、JIRAの課題IDをコミットログに含めることで、後々その変更の理由が分かるようになります。
関連するすべてのコミットで、課題IDを記録するようにしてください。
もちろん、課題に関連がなければ、課題IDを含める必要はありません。h4. Make sure your fork is up to date
自分のフォークが最新であることを確認する
Since the core developers must merge your commits into the main repository, it makes life much easier if your fork on GitHub is up to date before you send a pull request.
コア開発者があなたのコミットをメインリポジトリにマージしやすいように、プルリクエストを送る前に、GitHubの自分のフォークが最新になっているか確認してください。Let's say you have the main repository set up as a remote called "upstream" and you want to submit a pull request. Also, all your changes are currently on the local "mine" branch but not on "master". The first step involves pulling any changes from the main repository that have been added since you last fetched and merged:
たとえば、upstreamという名前でリモートに登録されたメインリポジトリがあり、そこに対してプルリクエストを送りたいとします。
また、すべての変更は現在、masterブランチではなく、ローカルのmineブランチにあるとします。
まず最初に、前回フェッチしてマージした以降に追加されているすべての変更をメインリポジトリからプルする必要があります:git checkout master git pull upstream
This should complete without any problems or conflicts. Next, rebase your local branch against the now up-to-date master:
これは何の問題もコンフリクトもなく終了するでしょう。
次に、今最新化したmasterに対して、ローカルブランチをリベースします:git checkout mine git rebase master
What this does is rearrange the commits such that all of your changes come after the most recent one in master. Think adding some cards to the top of a deck rather than shuffling them into the pack.
このコマンドが行ったのはコミットの並び替えです。
つまり、あなたのすべての変更はmaster上の最新の変更の後に並んでいます。
いくつかのカードを、中に混ぜ込むのではなく、デッキの一番上に追加したイメージです。You'll now be able to do a clean merge from your local branch to master:
さてこれでローカルブランチへからmasterにきれいにマージすることができます:git checkout master git merge mine
Finally, you must push your changes to your remote repository on GitHub, otherwise the core developers won't be able to pick them up:
最後に今回の変更をGitHub上のあなたのリモートリポジトリにプッシュします。
そうしないとコア開発者に見えないからです:git push
You're now ready to send the pull request from the GitHub user interface.
これでGitHubのユーザインタフェースからプルリクエストを送る準備ができました。h4. Say what your pull request is for
プルリクエストの理由を伝える
A pull request can contain any number of commits and it may be related to any number of issues. In the pull request message, please specify the IDs of all issues that the request relates to. Also give a brief description of the work you have done, such as: "I refactored the data binder and added support for custom number editors (GRAILS-xxxx)".
1つのプルリクエストには、複数のコミットを含めることができますし、また複数の課題に関連していても構いません。
プルリクエストのメッセージには、関連するすべての課題IDを記述してください。
また、今回の変更についての簡単な説明も記述してください。
たとえば、「I refactored the data binder and added support for custom number editors (GRAILS-xxxx)」のようにです。
20.4 Grailsドキュメントにパッチを送る
Contributing to the documentation is simpler for the core framework because there is a public fork of the http://github.com/grails/grails-doc project that anyone can request commit access to. So, if you want to submit patches to the documentation, simply request commit access to the following repository http://github.com/pledbrook/grails-doc by sending a GitHub message to 'pledbrook' and then commit your patches just as you would to any other GitHub repository.
ドキュメントについての貢献はコアフレームワークへの貢献よりも簡単です。
なぜなら、http://github.com/grails/grails-docプロジェクトの公開フォークがあり、誰でもコミット権をリクエストできるからです。
ドキュメントへのパッチを送りたい場合、GitHubの「pledbrook」にメッセージを送って、次のリポジトリhttp://github.com/pledbrook/grails-docに対するコミット権をリクエストしてください。
それから、あなたのパッチを他のGitHubリポジトリで普通に行っているようにコミットすればよいのです。h3. Building the Guide
ガイドをビルドする
To build the documentation, simply type:
ドキュメントをビルドするには、単純に以下を実行します:./gradlew docs
Be warned: this command can take a while to complete and you should probably increase your Gradle memory settings by giving the
注意点:
このコマンドは実行するのに時間がかかります。
また、次のようにGRADLE_OPTS environment variable a value likeGRADLE_OPTS環境変数を設定して、Gradleのメモリ使用量を増やした方が良いです。export GRADLE_OPTS="-Xmx512m -XX:MaxPermSize=384m"Fortunately, you can reduce the overall build time with a couple of useful options. The first allows you to specify the location of the Grails source to use:
幸いなことに、いくつかのオプションを使うことで、全体のビルド時間を減らすことができます。
まず、利用するGrailsのソースがどこにあるかを指定するオプションがあります:./gradlew -Dgrails.home=/home/user/projects/grails-core docs
The Grails source is required because the guide links to its API documentation and the build needs to ensure it's generated. If you don't specify a
Grailsのソースが必要なのは、ガイドがAPIドキュメントへのリンクを持っており、ビルド時にそれが生成されることを保証する必要があるからです。
もし、grails.home property, then the build will fetch the Grails source - a download of 10s of megabytes. It must then compile the Grails source which can take a while too.grails.homeプロパティを指定しないと、ビルド時にGrailsのソースファイル（10数MBあります）をダウンロードします。
そしてそのGrailsソースコードをコンパイルするため、より時間がかかるのです。Additionally you can create a local.properties file with this variable set:
さらに、以下の変数を設定しておくlocal.propertiesファイルを作成できます:grails.home=/home/user/projects/grails-core
or
またはgrails.home=../grails-core
The other useful option allows you to disable the generation of the API documentation, since you only need to do it once:
他には、毎回生成する必要がなければ、APIドキュメントの生成を無効化するという便利なオプションもあります:./gradlew -Ddisable.groovydocs=true docsAgain, this can save a significant amount of time and memory.
これでさらに、大幅に時間とメモリを削減できます。The main English user guide is generated in the
主となる英語のユーザーガイドはbuild/docs directory, with the guide sub-directory containing the user guide part and the ref folder containing the reference material. To view the user guide, simply open build/docs/index.html.build/docsディレクトリに作られます。
guideサブディレクトリにはユーザーガイドが、refフォルダにはリファレンスが入ります。
ユーザーガイドを表示するためには、単にbuild/docs/index.htmlを開きます。h3. Publishing
出力する
The publishing system for the user guide is the same as the one for Grails projects. You write your chapters and sections in the gdoc wiki format which is then converted to HTML for the final guide. Each chapter is a top-level gdoc file in the
ユーザーガイドの出力システムはGrailsプロジェクトのものと同じです。
章やセクションをgdoc wikiフォーマットで記述すれば、ガイドの最終版ではHTMLに変換されます。
それぞれの章はsrc/<lang>/guide directory. Sections and sub-sections then go into directories with the same name as the chapter gdoc but without the suffix.src/<lang>/guideディレクトリ直下のgdocファイルです。
セクションやサブセクションは、各章のgdocファイル名からサフィックスを除いた名前のサブフォルダに格納します。The structure of the user guide is defined in the
ユーザーガイドの構造は、YAML形式のsrc/<lang>/guide/toc.yml file, which is a YAML file. This file also defines the (language-specific) section titles. If you add or remove a gdoc file, you must update the TOC as well!src/<lang>/guide/toc.ymlファイルで定義されています。
このファイルは同時に各セクションの（各言語ごとの）タイトルも定義しています。
gdocファイルを追加・削除した場合、このTOCファイルも合わせて更新する必要があります！The
src/<lang>/ref directory contains the source for the reference sidebar. Each directory is the name of a category, which also appears in the docs. Hence the directories need different names for the different languages. Inside the directories go the gdoc files, whose names match the names of the methods, commands, properties or whatever that the files describe.src/<lang>/refディレクトリには「Quick Reference」というサイドバーのソースが格納されています。
各ディレクトリ名はカテゴリ名になっていて、カテゴリ名は本文にも現れます。
そのため、ディレクトリには言語ごとに違う名前が必要です。
そのディレクトリ内にgdocファイルが格納されます。gdocファイルの名前はメソッド名・コマンド名・プロパティ名やそのファイルが説明している何かに一致します。h3. Translations
翻訳
This project can host multiple translations of the user guide, with
このプロジェクトでは、src/en being the main one. To add another one, simply create a new language directory under src and copy into it all the files under src/en. The build will take care of the rest.src/enをオリジナルとして、さまざまな言語に翻訳されたユーザーガイドを提供しています。
新しい言語の翻訳を追加するには、単にsrcディレクトリに新しい言語のフォルダを作成し、src/enにあるすべてのファイルをコピーします。
ビルドすることで必要な作業が行われます。Once you have a copy of the original guide, you can use the
オリジナルのガイドをコピーしたら、置き換えようとしている英語の原文は削除せず、{hidden} macro to wrap the English text that you have replaced, rather than remove it. This makes it easier to compare changes to the English guide against your translation. For example:{hidden}マクロで英語の原文を囲んでください。
これにより容易に英語の原文と今回の翻訳の比較ができます。たとえば:{hidden}
When you create a Grails application with the [create-app|commandLine] command,
Grails doesn't automatically create an Ant build.xml file but you can generate
one with the [integrate-with|commandLine] command:
{hidden}Quando crias uma aplicação Grails com o comando [create-app|commandLine], Grails
não cria automaticamente um ficheiro de construção Ant build.xml mas podes gerar
um com o comando [integrate-with|commandLine]:Because the English text remains in your gdoc files,
英語の原文がgdocファイルに残っていることで、diff will show differences on the English lines. You can then use the output of diff to see which bits of your translation need updating. On top of that, the {hidden} macro ensures that the text inside it is not displayed in the browser, although you can display it by adding this URL as a bookmark: javascript:toggleHidden(); (requires you to build the user guide with Grails 2.0 M2 or later).diffで英語の行についての変更を表示することができます。
つまり、翻訳のどこをアップデートすればいいかを知るためにdiffの出力を使えるのです。
ブラウザで見るとき、{hidden}に囲まれた部分は表示されません。
ただし、ブックマークとしてjavascript:toggleHidden();を追加することで、{hidden}に囲まれた部分を表示できるようになります。
（これにはGrails 2.0以降でユーザーガイドがビルドされている必要があります。）Even better, you can use the
もっと便利に、left_to_do.groovy script in the root of the project to see what still needs translating. You run it like so:left_to_do.groovyスクリプトをプロジェクトのルートで実行すれば、まだ翻訳が必要な箇所をしることができます。
このように実行します:./left_to_do.groovy es
This will then print out a recursive diff of the given translation against the reference English user guide. Anything in
このコマンドは、オリジナルの英語のユーザーガイドと対象となる翻訳との差分を再帰的に実行し、結果を出力します。
{hidden} blocks that hasn't changed since being translated will not appear in the diff output. In other words, all you will see is content that hasn't been translated yet and content that has changed since it was translated. Note that {code} blocks are ignored, so you don't need to include them inside {hidden} macros.{hidden}ブロックに含まれていて、翻訳されたあと変更されていない部分は差分として出力されません。
言い換えれば、翻訳されたあと原文が修正されたのに、まだ再翻訳されていない部分が表示されます。
{code}ブロックは無視されるため、{code}ブロックを{hidden}で囲む必要は ありません 。To provide translations for the headers, such as the user guide title and subtitle, just add language specific entries in the 'resources/doc.properties' file like so:
ユーザーガイドのタイトルやサブタイトルなど、ヘッダ部分の翻訳をするには、resources/doc.propertiesファイルに、次のように各言語に固有のエントリを追加します:es.title=El Grails Framework es.subtitle=...
For each language translation, properties beginning
それぞれの言語の翻訳において、<lang>. will override the standard ones. In the above example, the user guide title will be El Grails Framework for the Spanish translation. Also, translators can be credited by adding a '<lang>.translators' property:<lang>.で始まるプロパティは標準のプロパティを上書きします。
上記の例で言えば、スペイン語の翻訳ではユーザーガイドのタイトルが「El Grails Framework」となります。
同様に、翻訳者も<lang>.translatorsプロパティを追加することでクレジットに名前を載せることができます:fr.translators=Stéphane Maldini
This should be a comma-separated list of names (or the native language equivalent) and it will be displayed as a "Translated by" header in the user guide itself.
このプロパティはカンマ区切りの名前のリストになり、ユーザーガイドに「Translated by」ヘッダとして表示されます。You can build specific translations very easily using the
特定の言語の翻訳は、publishGuide_* and publishPdf_* tasks. For example, to build both the French HTML and PDF user guides, simply executepublishGuide_*やpublishPdf_*を使えば簡単にビルドできます。
たとえば、フランス語のHTMLとPDFのユーザーガイドをビルドするには、単純に以下を実行します:./gradlew publishPdf_fr
Each translation is generated in its own directory, so for example the French guide will end up in
それぞれの翻訳は、言語別のディレクトリに作成されます。
たとえば、フランス語のガイドはbuild/docs/fr. You can then view the translated guide by opening build/docs/<lang>/index.html.build/docs/frに作られます。
翻訳されたガイドは、build/docs/<lang>/index.htmlを開けば見られます。All translations are created as part of the Hudson CI build for the grails-doc project, so you can easily see what the current state is without having to build the docs yourself.
すべての翻訳結果はgrails-docのHudson CIビルドプロジェクトの一部として作成されています。
そのため、現状の最新ドキュメントは自分でビルドしなくても見ることができます。