本日は
Julia アドベントカレンダー $N=8$ です
タイトル通り Julia のマニュアル・ドキュメントを日本語で読む方法を紹介します．
いくつかの方法があります．
UnofficialJuliaDoc-ja にアクセスする
これが一番簡単な方法です．下記リンク先に行けばOKです．
自分でビルドする
ソースコードは下記で管理しています．各自の環境でホストすることもできます．OpenAI の API キーをあらかじめ用意しておいてください．
大まかな方針は下記の通りです．
- Markdown ファイルを読み込む箇所にドキュメントを翻訳するフックを挿入
- Markdown をパースしてパラグラフ毎に翻訳エンジンを用いて英語を日本語に翻訳する．翻訳エンジンとしては OpenAI API を使用．
- 翻訳が失敗する箇所は原文を表示するようにフォールバックしています．ここは手動で直すことが可能
-
cd julia && make -C julia && make -C julia/docをする- Julia をソースからビルドするのは Julia の公式ドキュメントをビルドする際，ソースからビルドされた Julia を使うことを前提とする仕組みになってるようです．一方で，Documenter.jl や Pkg.jl など他のサードパーティパッケージであれば公式で配布されている Julia を使って翻訳作業をすることができます
マニュアル(Docstring) を日本語で読む方法
まず，DocstringTranslation.jl パッケージをインストールします．
julia> using Pkg; Pkg.add("DocstringTranslation")
次に次の手順で翻訳済みマークダウンを特定の場所に保存します．
$ git clone https://github.com/AtelierArith/UnofficialJuliaDoc-ja.git
$ mkdir -p ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97
$ mv UnofficialJuliaDoc-ja/translation ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/
$ cd ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97
$ ls
translation # このディレクトリがあることを確認する
この translation に事前翻訳済みのマニュアルが入っています．
以上の準備ができたら翻訳された結果を表示することができます．
julia> using DocstringTranslation
julia> @switchlang! :ja
julia> @doc sin
下記のような結果が出ると思います．
help?> sin
search: sin sign sinh sind asin sinc in min isinf asinh sinpi asind using stdin size skip sprint Main sincos join bind string Cint islink signed
sin(x::T) where {T <: Number} -> float(T)
xの正弦を計算します。xはラジアンで指定されます。
isinf(x)の場合はDomainErrorをスローし、isnan(x)の場合はT(NaN)を返します。
他にsind、sinpi、sincos、cis、asinも参照してください。
例
≡≡
julia> round.(sin.(range(0, 2pi, length=9)'), digits=3)
1×9 Matrix{Float64}:
0.0 0.707 1.0 0.707 0.0 -0.707 -1.0 -0.707 -0.0
julia> sind(45)
0.7071067811865476
julia> sinpi(1/4)
0.7071067811865475
julia> round.(sincos(pi/6), digits=3)
(0.5, 0.866)
julia> round(cis(pi/6), digits=3)
0.866 + 0.5im
julia> round(exp(im*pi/6), digits=3)
0.866 + 0.5im
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
sin(A::AbstractMatrix)
正方行列 A の行列サインを計算します。
A が対称またはエルミートの場合、その固有分解（eigen）を使用してサインを計算します。そうでない場合、サインは exp
を呼び出すことによって決定されます。
例
≡≡
julia> sin(fill(1.0, (2,2)))
2×2 Matrix{Float64}:
0.454649 0.454649
0.454649 0.454649
他にいろいろ試してみてください．翻訳に不満があれば翻訳済み結果が入っている translation ディレクトリで当該の翻訳箇所を修正することで良い感じにできます．
SpecialFunction.jl のようなサードパーティの結果は入っていないのでそれを読みたい場合は OpenAI API キーを用意して OPENAI_API_KEY という名前の環境変数に値をセットしておいておくと動的に翻訳してくれます．翻訳結果はローカルに保存されるので次回からはAPIを呼び出さずキャッシュ結果を利用します．
まとめ
Julia のマニュアル・ドキュメントを日本語で読む方法を紹介しました．
OpenAI の翻訳なのでややぎこちないかもしれませんが，英語で書かれてる時に比べて意外と読み落としている箇所があったりして深い理解につながりやすくなってると思います．翻訳の質は LLM の質に依存していますが，手動で修正することもできるので必要に応じてPRを送ってください．