DocstringTranslation.jl

DocstringTranslation.jl は、Julia のドキュメント（docstring）を自動的に翻訳するためのパッケージです。OpenAI API を利用して、ドキュメントの多言語化を支援します。翻訳の品質は OpenAI API の性能に依存します．

(English follows Japanese)

主な機能

ドキュメント文字列の自動翻訳
翻訳結果のキャッシュ機能
Documenter.jl との統合

基本的な使い方

指数関数 $e^x$ を計算する関数 exp に対応する docstring を日本語で表示してみましょう．ワンライナーで実行できます．

julia> using DotEnv; DotEnv.load!(); using DocstringTranslation; @switchlang! "ja"; @doc exp
  exp(x)

  xの自然基底指数を計算します。言い換えれば、ℯ^xです。

  他にexp2、exp10、およびcisも参照してください。

  例
  ≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi) ≈ cis(pi)
  true

  exp(A::AbstractMatrix)

  行列 A の行列指数関数を計算します。これは次のように定義されます。

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  対称行列またはエルミート行列 A
  の場合は、固有分解（eigen）が使用され、それ以外の場合はスケーリングと平方化アルゴリズムが選択されます（詳細は
  [^H05] を参照）。

  │ [^H05]
  │
  │  Nicholas J. Higham, "The squaring and scaling method for the matrix exponential
  │  revisited", SIAM Journal on Matrix Analysis and Applications, 26(4), 2005, 1179-1193.
  │  doi:10.1137/090768539 (https://doi.org/10.1137/090768539)

  例
  ≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

@doc exp の代わりにヘルプモードに移行し help?> exp を実行しても構いません．

設定

翻訳先の言語設定

@switchlang! lang のようにマクロを使用して翻訳先の言語を設定します：

julia> @switchlang! "ja"  # 日本語に翻訳
julia> @switchlang! "de"  # ドイツ語に翻訳

ここで， "ja" は ISO 639-1 に登録されている日本語に対応する言語コードです．値 lang は OpenAI API が提供するシステムプロンプトに渡されます．したがって，ChatGPT が lang の意味を適切に解釈できる限り，ユーザはこの値を自由に選択することができます．

REPL のセッションを起動する度に OpenAI API 毎回呼び出すことを避けるために，DocstringTranslation パッケージは翻訳結果をキャッシュする機能を実装しています．この機能は Scratch.jl パッケージによって実現されています．デフォルトでは joinpath(DEPOT_PATH[1], "scratchspaces", "d404e13b-1f8e-41a5-a26a-0b758a0c6c97", "translation") 以下に格納されます．要するに ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation のことです．d404e13b-1f8e-41a5-a26a-0b758a0c6c97 は我々のパッケージ DocstringTranslation の UUID を指しています． tree コマンドでディレクトリの構造を調べてみましょう：

$ tree ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation
├── Base
│   └── 1.11
│       └── Math
│           └── 77be4ada26c623c913ebbdae5d8450a4dfe8f3cbf67837faac9d7193342d2bfe
│               ├── ja.md
│               └── original.md
└── LinearAlgebra
    └── 1.11
        └── 46c0494a8a2adffc6f71752b60448da1743997b5b1791b71e3830113e9b9cc46
            ├── ja.md
            └── original.md

8 directories, 4 files

@doc exp を実行することで Julia は exp に関する docstring を収集します．先ほどのデモンストレーションでは exp(x) と exp(A::AbstractMatrix) に対する２種類の docstring を収集していました．各は Math v1.11, LinearAlgebra v1.11 モジュール内で定義されているのでこのようなディレクトリ構造が生まれます． 77be4ada26c623c913ebbdae5d8450a4dfe8f3cbf67837faac9d7193342d2bfe や 46c0494a8a2adffc6f71752b60448da1743997b5b1791b71e3830113e9b9cc46 などは原文 (original.md に格納されている格納する) のハッシュ値です．original.md は手動で変更しないでください．翻訳結果に不満があれば ja.md を編集することで所望の翻訳結果を得ることができます．

翻訳結果のキャッシュディレクトリを変更する場合は、以下の関数を使用します：

switchtranslationcachedir!("path/to/cache/directory")

注意事項

翻訳の品質は OpenAI API の性能に依存します

DocstringTranslation.jl

DocstringTranslation.jl is a package for automatically translating Julia documentation (docstrings). It uses the OpenAI API to support multilingual documentation. The translation quality depends on the performance of the OpenAI API.

Main Features

Automatic translation of documentation strings
Translation result caching
Integration with Documenter.jl

Installation

julia> using Pkg
julia> Pkg.add("DocstringTranslation")

You need to set up your OpenAI API key. Set the environment variable OPENAI_API_KEY. You may also find the OpenAI.jl README helpful.

You can avoid explicitly setting OPENAI_API_KEY by using the DotEnv.jl package. Place a .env file in your working directory and set your OpenAI API key in that file:

# .env
OPENAI_API_KEY=sk-<your-key-here>

You can automatically set ENV["OPENAI_API_KEY"] by opening the REPL and running:

julia> using DotEnv; DotEnv.load!()

Let's indirectly verify that ENV["OPENAI_API_KEY"] is set:

julia> @assert haskey(ENV, "OPENAI_API_KEY")

That completes the setup.

Basic Usage

Let's display the docstring for the exp function, which calculates the exponential function $e^x$, in Japanese. You can do this in one line:

julia> using DotEnv; DotEnv.load!(); using DocstringTranslation; @switchlang! "ja"; @doc exp
  exp(x)

  xの自然基底指数を計算します。言い換えれば、ℯ^xです。

  他にexp2、exp10、およびcisも参照してください。

  例
  ≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi) ≈ cis(pi)
  true

  exp(A::AbstractMatrix)

  行列 A の行列指数関数を計算します。これは次のように定義されます。

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  対称行列またはエルミート行列 A
  の場合は、固有分解（eigen）が使用され、それ以外の場合はスケーリングと平方化アルゴリズムが選択されます（詳細は
  [^H05] を参照）。

  │ [^H05]
  │
  │  Nicholas J. Higham, "The squaring and scaling method for the matrix exponential
  │  revisited", SIAM Journal on Matrix Analysis and Applications, 26(4), 2005, 1179-1193.
  │  doi:10.1137/090768539 (https://doi.org/10.1137/090768539)

  例
  ≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

Instead of @doc exp, you can also enter help mode and run help?> exp.

Notes

Translation quality depends on the performance of the OpenAI API

DocstringTranslation.jl

主な機能

インストール

基本的な使い方

設定

翻訳先の言語設定

キャッシュディレクトリの設定

注意事項

DocstringTranslation.jl

Main Features

Installation

Basic Usage

Notes