sghtmltopdf 0.4.0 → 0.5.1

data/ext/sghtmltopdf/src/gvl.rs

@@ -1,30 +1,30 @@
-//! GVL(Global VM Lock)の解放。
+//! Releasing the GVL (Global VM Lock).
 //!
-//! レンダリングの間はGVLを解放し、Pumaの他スレッドを止めないようにする。
+//! The GVL is released during rendering so Puma's other threads are not blocked.
 
 use std::ffi::c_void;
 use std::panic::{catch_unwind, resume_unwind, AssertUnwindSafe};
 
-/// GVLを解放して`func`を実行する。
+/// Release the GVL and run `func`.
 ///
-/// # なぜ`Send`境界が要るか
+/// # Why the `Send` bound is needed
 ///
-/// magnusは「GVLを解放するAPIは存在しない」前提でGVL状態をスレッド
-/// ローカルにキャッシュしており(`magnus::api`の *assumed not to change
-/// because there's currently no api to unlock*)、ここで解放しても
-/// `Ruby::get()`は`Ok`を返してしまう。返ったハンドルでRubyに触ればUBになる。
+/// magnus caches the GVL state in a thread local on the assumption that "there is no API
+/// that releases the GVL" (*assumed not to change because there's currently no api to
+/// unlock* in `magnus::api`), so `Ruby::get()` returns `Ok` even after we release it here.
+/// Touching Ruby through the handle it returns would be UB.
 ///
-/// `Send`境界を課すと、magnusの値(`NonNull<RBasic>`)も`Ruby`ハンドル
-/// (`*mut ()`)も`!Send`なのでキャプチャがコンパイルエラーになる。
-/// クロージャの中で改めて`Ruby::get()`を呼ぶことまでは型では防げないが、
-/// 解放区間で呼ぶのは`sghtmltopdf_core`の関数だけであり、コアはRubyを
-/// 一切知らないため到達しない。
+/// Imposing a `Send` bound makes capturing a magnus value (`NonNull<RBasic>`) or a `Ruby`
+/// handle (`*mut ()`) a compile error, both being `!Send`.
+/// Calling `Ruby::get()` again inside the closure is not something the types can prevent,
+/// but the only things called in the released region are `sghtmltopdf_core` functions, and
+/// the core knows nothing about Ruby, so it is unreachable.
 ///
-/// # 割り込み
+/// # Interruption
 ///
-/// UBF(unblock function)は`None`＝割り込み不可。`Kernel#trap`やCtrl-Cでの
-/// 中断は初期スコープ外とする。
-#[allow(dead_code)] // 将来のGVL解放実装で使う
+/// The UBF (unblock function) is `None`, meaning uninterruptible. Interruption through
+/// `Kernel#trap` or Ctrl-C is outside the initial scope.
+#[allow(dead_code)] // used by the future GVL-releasing implementation
 pub fn without_gvl<F, R>(func: F) -> R
 where
     F: FnOnce() -> R + Send,
@@ -41,9 +41,9 @@ where
         R: Send,
     {
         let state = unsafe { &mut *(arg as *mut State<F, R>) };
-        let func = state.func.take().expect("コールバックが2度呼ばれました");
-        // パニックがFFI境界を越えるとプロセスがabortするため、ここで捕まえて
-        // GVLを取り戻してからRust側でresumeする。
+        let func = state.func.take().expect("the callback was called twice");
+        // A panic crossing the FFI boundary aborts the process, so it is caught here and
+        // resumed on the Rust side after the GVL is reacquired.
         state.result = Some(catch_unwind(AssertUnwindSafe(func)));
         std::ptr::null_mut()
     }
@@ -60,26 +60,26 @@ where
             std::ptr::null_mut(),
         );
     }
-    match state.result.expect("コールバックが実行されませんでした") {
+    match state.result.expect("the callback was never run") {
         Ok(value) => value,
         Err(panic) => resume_unwind(panic),
     }
 }
 
-/// GVLを取り戻して`func`を実行する。[`without_gvl`]の内側からだけ呼ぶ。
+/// Reacquire the GVL and run `func`. Call only from inside [`without_gvl`].
 ///
-/// `without_gvl`と違い`Send`境界は課さない。ここはGVLを保持している＝Rubyに
-/// 触ってよい区間だから。
+/// Unlike `without_gvl` it imposes no `Send` bound, this being a region where the GVL is
+/// held and Ruby may be touched.
 ///
-/// # 呼び出し側が守ること(libruby側の制約)
+/// # What the caller must observe (libruby's constraints)
 ///
-/// * `func`からRubyのオブジェクトを返さない。返すとGVLを再び手放した
-///   あとGCのスコープから外れ、マークされない。値を持ち帰るときは
-///   `rb_gc_register_address`で登録したスロットへ入れること
+/// * Do not return a Ruby object from `func`. Returning one puts it outside the GC's scope
+///   once the GVL is released again, and it will not be marked. To carry a value back, put
+///   it in a slot registered with `rb_gc_register_address`
 ///   (`callback_sink::ValueSlot`)
-/// * `func`から例外を投げさせない。longjmpがこの関数を飛び越えると
-///   未定義動作になる。Rubyの呼び出しは必ず`rb_protect`相当で包む
-///   (magnusの`Proc::call`は内部で`protect`しているのでそのまま使える)
+/// * Do not let `func` throw an exception. A longjmp jumping over this function is undefined
+///   behaviour. Every Ruby call must be wrapped in the equivalent of `rb_protect`
+///   (magnus's `Proc::call` uses `protect` internally, so it can be used directly)
 pub fn with_gvl<F, R>(func: F) -> R
 where
     F: FnOnce() -> R,
@@ -94,8 +94,8 @@ where
         F: FnOnce() -> R,
     {
         let state = unsafe { &mut *(arg as *mut State<F, R>) };
-        let func = state.func.take().expect("コールバックが2度呼ばれました");
-        // パニックがlibrubyのフレームを越えるとプロセスがabortする。
+        let func = state.func.take().expect("the callback was called twice");
+        // A panic crossing a libruby frame aborts the process.
         state.result = Some(catch_unwind(AssertUnwindSafe(func)));
         std::ptr::null_mut()
     }
@@ -107,7 +107,7 @@ where
     unsafe {
         rb_sys::rb_thread_call_with_gvl(Some(call::<F, R>), &mut state as *mut _ as *mut c_void);
     }
-    match state.result.expect("コールバックが実行されませんでした") {
+    match state.result.expect("the callback was never run") {
         Ok(value) => value,
         Err(panic) => resume_unwind(panic),
     }

data/ext/sghtmltopdf/src/lib.rs

@@ -1,8 +1,8 @@
-//! Ruby拡張のエントリポイント。
+//! The Ruby extension's entry point.
 //!
-//! この層は薄く保つ。オプションの引数列(argv)への組み立てはRuby側が
-//! 行い、ここは受け取ったargvをCLI・HTTPサーバと同じパーサへ通して
-//! レンダリングするだけ。
+//! This layer is kept thin. Assembling the option argument list (argv) is done on the Ruby
+//! side, and this merely runs the argv it receives through the same parser as the CLI and
+//! the HTTP server, and renders.
 
 mod callback_sink;
 mod errors;
@@ -13,81 +13,75 @@ use std::path::PathBuf;
 
 use magnus::rb_sys::AsRawValue;
 use magnus::{block::Proc, function, prelude::*, Error, RString, Ruby};
-use sghtmltopdf_core::cli::{self, convert};
-use sghtmltopdf_core::render_stack;
-use sghtmltopdf_core::sink::{FileSink, MemorySink};
+use sghtmltopdf_core::{with_render_stack, ConvertError, Converter, FileSink};
 
 use callback_sink::{pump_to_block, BlockSlot, PendingUnwind, ValueSlot};
 
-/// HTMLを変換してPDFのバイト列を返す。
+/// Convert HTML and return the PDF bytes.
 fn render(html: RString, argv: Vec<String>) -> Result<RString, Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
-    // GVLを解放する前にRust側へコピーする。解放中はRubyのオブジェクトに
-    // 触れないため、`RString`のままでは持ち込めない。
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
+    // Copy to the Rust side before releasing the GVL. Ruby objects cannot be touched while
+    // it is released, so an `RString` cannot be carried in.
     let html = unsafe { html.as_slice() }.to_vec();
     errors::catch_panic(&ruby, move || render_inner(html, argv))
 }
 
 fn render_inner(html: Vec<u8>, argv: Vec<String>) -> Result<RString, Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
-    let (args, fonts) = cli::parse_convert_argv(&argv).map_err(|e| errors::to_ruby(&ruby, e))?;
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
+    let converter = Converter::from_args(argv).map_err(|e| errors::to_ruby(&ruby, e))?;
 
-    // GVLを解放したうえで、さらにレンダリング専用のスタックを確保した
-    // スレッドへ移す。Rubyのスレッドのマシンスタックは既定1MiBしかなく、
-    // レイアウト・描画の再帰に耐えられないため(`callback_sink`のモジュール
-    // doc参照)。この経路はRubyへコールバックしないので、そのまま移せる。
+    // Release the GVL and then move onto a thread with a stack allocated specifically for
+    // rendering. A Ruby thread's machine stack is only 1MiB by default and cannot survive the
+    // recursion of layout and drawing (see the module docs of `callback_sink`).
+    // This path never calls back into Ruby, so it can be moved as-is.
     let pdf = gvl::without_gvl(move || {
-        render_stack::with_render_stack(move || {
-            convert::render_to_memory(&args, &fonts, Cursor::new(html), MemorySink::new())
-        })
+        with_render_stack(move || converter.render_to_vec(Cursor::new(html)))
     })
     .map_err(|e| errors::to_ruby(&ruby, e))?;
 
     Ok(ruby.str_from_slice(&pdf))
 }
 
-/// HTMLを変換して`path`へ書き出す。
+/// Convert HTML and write it to `path`.
 ///
-/// 出力先は[`FileSink`]が決めるので、argvの`--output`は使われない
-/// (一時ファイルへ書いて成功時だけrenameするため、途中で失敗しても
-/// 壊れたPDFが残らない)。
+/// The destination is decided by [`FileSink`]
+/// (it writes to a temporary file and renames only on success, so a failure part-way through
+/// leaves no broken PDF).
 fn render_to_file(html: RString, argv: Vec<String>, path: String) -> Result<(), Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
     let html = unsafe { html.as_slice() }.to_vec();
     errors::catch_panic(&ruby, move || render_to_file_inner(html, argv, path))
 }
 
 fn render_to_file_inner(html: Vec<u8>, argv: Vec<String>, path: String) -> Result<(), Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
-    let (args, fonts) = cli::parse_convert_argv(&argv).map_err(|e| errors::to_ruby(&ruby, e))?;
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
+    let converter = Converter::from_args(argv).map_err(|e| errors::to_ruby(&ruby, e))?;
 
     let path = PathBuf::from(path);
     let sink = FileSink::create(&path).map_err(|e| {
         errors::to_ruby(
             &ruby,
-            cli::CliError::Input(format!("{}の作成に失敗しました: {e}", path.display())),
+            ConvertError::Input(format!("failed to create {}: {e}", path.display())),
         )
     })?;
 
-    gvl::without_gvl(move || {
-        render_stack::with_render_stack(move || convert::render(&args, &fonts, Cursor::new(html), sink))
-    })
-    .map_err(|e| errors::to_ruby(&ruby, e))?;
+    gvl::without_gvl(move || with_render_stack(move || converter.render(Cursor::new(html), sink)))
+        .map_err(|e| errors::to_ruby(&ruby, e))?;
     Ok(())
 }
 
-/// HTMLを変換し、確定したPDFのバイト列を`chunk_size`ごとに`block`へ渡す。
+/// Convert HTML and hand the settled PDF bytes to `block` in `chunk_size` pieces.
 ///
-/// レンダリングの間はGVLを解放し、ブロックを呼ぶ瞬間だけ取り戻す。ブロックが
-/// 例外を投げた場合は、その例外をそのまま呼び出し元へ伝える(エンジン側は
-/// 通常のエラーパスで巻き戻る)。
+/// The GVL is released during rendering and reacquired only for the moment the block is
+/// called. If the block throws an exception, that exception is propagated to the caller
+/// unchanged (the engine unwinds through its ordinary error path).
 fn render_each(
     html: RString,
     argv: Vec<String>,
     block: Proc,
     chunk_size: usize,
 ) -> Result<(), Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
     let html = unsafe { html.as_slice() }.to_vec();
     errors::catch_panic(&ruby, move || {
         render_each_inner(html, argv, block, chunk_size)
@@ -100,11 +94,11 @@ fn render_each_inner(
     block: Proc,
     chunk_size: usize,
 ) -> Result<(), Error> {
-    let ruby = Ruby::get().expect("GVLを保持したまま呼ばれるはず");
-    let (args, fonts) = cli::parse_convert_argv(&argv).map_err(|e| errors::to_ruby(&ruby, e))?;
+    let ruby = Ruby::get().expect("it should be called while holding the GVL");
+    let converter = Converter::from_args(argv).map_err(|e| errors::to_ruby(&ruby, e))?;
 
-    // ブロックはGVL解放区間をまたいで生きる必要があるため、GCへ登録する
-    // (解放後にスタックへ積んだ値は保守的GCの走査対象外)。
+    // The block has to survive across the GVL-released region, so it is registered with the
+    // GC (a value pushed onto the stack after the release is outside the conservative GC's scan).
     let block = ValueSlot::new(block.as_raw());
     let mut pending = PendingUnwind::default();
 
@@ -112,47 +106,50 @@ fn render_each_inner(
         let slot = BlockSlot::new(&block);
         let pending = &mut pending;
         gvl::without_gvl(move || {
-            // レンダリングは専用スタックのスレッドで走り、確定したチャンクだけが
-            // ここへ戻ってくる。ブロックの呼び出し(=GVLの再取得)は、GVLを
-            // 手放したこのスレッドで行う必要があるため`pump_to_block`に任せる。
+            // Rendering runs on a thread with a dedicated stack, and only the settled chunks
+            // come back here. Calling the block (that is, reacquiring the GVL) has to happen
+            // on this thread, the one that released it, so it is left to `pump_to_block`.
             pump_to_block(slot, pending, chunk_size, move |sink| {
-                convert::render(&args, &fonts, Cursor::new(html), sink)
+                converter.render(Cursor::new(html), sink)
             })
         })
     };
     drop(block);
 
-    // ブロック由来の中断は、エンジンが返すエラーより優先して伝える
-    // (`Sink::Error`が`io::Error`固定のため、理由はこちらに載っている)。
-    // `break`等の脱出は`into_error`の中で`rb_jump_tag`し戻らないので、
-    // Rust側の値はここで落としきってから呼ぶ。
+    // An interruption from the block is propagated in preference to whatever error the engine
+    // returns (`Sink::Error` is fixed to `io::Error`, so the reason rides on this instead).
+    // A non-local exit such as `break` calls `rb_jump_tag` inside `into_error` and never
+    // returns, so the Rust-side values are all dropped before it is called.
     if pending.is_pending() {
         drop(result);
         return Err(pending
             .into_error()
-            .expect("is_pendingがtrueなら中断が入っている"));
+            .expect("with is_pending true, an interruption is present"));
     }
     result.map_err(|e| errors::to_ruby(&ruby, e))
 }
 
-/// coreへリンクできていることの確認用(疎通確認)。
+/// For confirming we can link against the core (a connectivity check).
 fn core_version() -> String {
     env!("CARGO_PKG_VERSION").to_string()
 }
 
-/// coreのシンボルを実際に1つ呼んでリンクを確かめる。
+/// Really call one of the core's symbols to confirm the link.
 fn default_page_size() -> String {
-    let settings = sghtmltopdf_core::layout::PageSettings::default();
+    let settings = sghtmltopdf_core::PageSettings::default();
     format!("{}x{}", settings.size.width, settings.size.height)
 }
 
-/// GVLを解放して実行できることの確認用。解放中も他のRubyスレッドが
-/// 進めることをRuby側のテストで検証する。
+/// For confirming it can run with the GVL released. That other Ruby threads make progress
+/// during the release is checked by a test on the Ruby side.
 fn sleep_without_gvl(ms: u64) {
     gvl::without_gvl(|| std::thread::sleep(std::time::Duration::from_millis(ms)));
 }
 
-#[magnus::init]
+// The exported symbol has to match the `.so` file name, which stays `sghtmltopdf`. Without
+// this the name would come from the package (`sghtmltopdf-ruby`) and Ruby would look for an
+// `Init_sghtmltopdf` that does not exist.
+#[magnus::init(name = "sghtmltopdf")]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Sghtmltopdf")?;
     errors::define(ruby, module)?;

data/lib/sghtmltopdf/configuration.rb

@@ -1,24 +1,24 @@
 # frozen_string_literal: true
 
 module Sghtmltopdf
-  # グローバルな既定オプション。
+  # The global default options.
   #
   #   Sghtmltopdf.configure do |c|
   #     c.page_size   = "A4"
   #     c.gothic_font = "/path/to/NotoSansJP-Regular.ttf"
   #   end
   #
-  # ここで設定した値は`render`/`render_to_file`の引数で上書きできる
-  # (マージ順はグローバル → 呼び出し時)。
+  # A value set here can be overridden by an argument to `render`/`render_to_file`
+  # (merged in the order global, then call-time).
   #
-  # キー名の妥当性は検査しない。オプション定義はRust側(`cli/options.rs`)の
-  # 1箇所に集約する方針のため、未知のキーはレンダリング時にclapが`UsageError`をraiseする。
+  # Key names are not validated. The option definitions live in one place on the Rust side
+  # (`cli/options.rs`), so an unknown key makes clap raise a `UsageError` at render time.
   class Configuration
     def initialize(options = {})
       @options = {}
-      # 明示的に設定した値(@options)と、Railtieなどが流し込んだ既定値
-      # (@defaults)は分けて持つ。読み出しは常に@optionsが勝つので、
-      # イニシャライザの実行順に依存しない。
+      # Values set explicitly (@options) are kept separately from the defaults injected by
+      # the Railtie and others (@defaults). Reads always prefer @options, so nothing depends
+      # on the order the initialisers run in.
       @defaults = {}
       options.each { |key, value| self[key] = value }
     end
@@ -32,30 +32,30 @@ module Sghtmltopdf
       @options[Options.canonical_key(key)] = value
     end
 
-    # @param with_defaults [Boolean] 流し込まれた既定値を含めるか。
-    #   HTTPサーバへ委譲するときは`false`にする。Rails向けの既定値
-    #   (`base_url`・`allow`)はローカルのファイル解決のためのもので、
-    #   サーバモードではリクエストから指定できないキーだから
+    # @param with_defaults [Boolean] whether to include the injected defaults.
+    #   Set it to `false` when delegating to the HTTP server: the Rails-oriented defaults
+    #   (`base_url` and `allow`) exist for local file resolution and are keys server mode
+    #   cannot take from a request
     def to_h(with_defaults: true)
       with_defaults ? @defaults.merge(@options) : @options.dup
     end
 
-    # 既定値を流し込む。Railtieが Rails向けの既定値を入れるのに使う。
-    # 明示的に設定された値より弱い(順序に関係なく`[]=`が勝つ)。
+    # Inject the defaults. Used by the Railtie to set the Rails-oriented defaults.
+    # They are weaker than explicitly set values (`[]=` wins regardless of order).
     def apply_defaults(defaults)
       defaults.each { |key, value| @defaults[Options.canonical_key(key)] = value }
       self
     end
 
-    # `c.page_size = "A4"`と`c.page_size`を受ける。
+    # Accepts both `c.page_size = "A4"` and `c.page_size`.
     def method_missing(name, *args)
       key = name.to_s
       if key.end_with?("=")
-        raise ArgumentError, "#{name}は引数1つを取ります" unless args.size == 1
+        raise ArgumentError, "#{name} takes one argument" unless args.size == 1
 
         self[key.chomp("=")] = args.first
       else
-        raise ArgumentError, "#{name}は引数を取りません" unless args.empty?
+        raise ArgumentError, "#{name} takes no arguments" unless args.empty?
 
         self[key]
       end

data/lib/sghtmltopdf/options.rb

@@ -3,44 +3,42 @@
 require "uri"
 
 module Sghtmltopdf
-  # オプションハッシュを変換する。
+  # Converts an options hash into:
   #
-  # * ネイティブ拡張へ渡すCLIの引数列(argv) … [.to_argv]
-  # * HTTPサーバモードへ渡すクエリ文字列   … [.to_query]
+  # * the CLI argument list (argv) passed to the native extension ... [.to_argv]
+  # * the query string passed to HTTP server mode                 ... [.to_query]
   module Options
-    # 入力は常に標準入力を表す`-`を置く(実際のバイト列はFFIで直接渡すため
-    # 読まれない)。出力先はRust側のSinkが決めるので、ここもダミーの`-`。
-    # `-`入力のときCLIは`--output`を必須にするため、省略はできない。
-    ARGV_PREFIX = ["sghtmltopdf", "-", "--output", "-"].freeze
 
-    # Ruby側だけで解釈するキー。変換オプションではないので、argvにも
-    # クエリにも出さない。
+    # The keys interpreted on the Ruby side alone. They are not conversion options, so they
+    # appear in neither the argv nor the query.
     TRANSPORT_KEYS = %i[server_url server_open_timeout server_read_timeout chunk_size].freeze
 
-    # 別名のキー(値は正規名)。CLIは`--allow`を`--allow-path`の別名として
-    # 受けるが、Ruby側は2つのキーのまま持ち回ってはいけない。既定が一方の
-    # キー、呼び出し時の指定がもう一方のキーだと、ハッシュのマージでは
-    # 上書きにならず両方がargvへ出てしまう(同じフラグの繰り返しは
-    # 「置き換え」ではなく「合併」の意味になる)。
+    # Alias keys (values are the canonical names). The CLI accepts `--allow` as an
+    # alias of `--allow-path`, but the Ruby side must not carry both keys around.
+    # If the defaults use one key and the call uses the other, a hash merge does
+    # not override: both end up in argv (repeating the same flag means "union",
+    # not "replace").
     ALIAS_KEYS = {allow: :allow_path}.freeze
 
     module_function
 
-    # 別名のキーを正規名へ寄せる。
+    # Map an alias key to its canonical name.
     def canonical_key(key)
       key = key.to_sym
       ALIAS_KEYS.fetch(key, key)
     end
 
-    # ハッシュのキーをまとめて正規化する。
+    # Normalize all keys of a hash.
     def canonicalize(options)
       options.to_h { |key, value| [canonical_key(key), value] }
     end
 
-    # @param options [Hash] Rubyのオプションハッシュ
-    # @return [Array<String>] clapへ渡す引数列
+    # @param options [Hash] the Ruby options hash
+    # @return [Array<String>] the conversion options passed to the core's `Converter`.
+    #   The HTML and the destination travel over FFI, so there is no program name, input
+    #   path or `--output` here.
     def to_argv(options)
-      argv = ARGV_PREFIX.dup
+      argv = []
       each_pair(options) do |name, value|
         argv.push("--#{name}")
         argv.push(value) unless value.nil?
@@ -48,18 +46,18 @@ module Sghtmltopdf
       argv
     end
 
-    # @param options [Hash] Rubyのオプションハッシュ
-    # @return [String] `POST /pdf`のクエリ文字列(先頭に`?`は付けない)
+    # @param options [Hash] the Ruby options hash
+    # @return [String] the query string for `POST /pdf` (with no leading `?`)
     def to_query(options)
       parts = []
       each_pair(options) do |name, value|
-        # 値なしのフラグはキーだけを置く(サーバは値なし＝真として扱う)。
+        # A valueless flag becomes just the key (the server treats no value as true).
         parts << (value.nil? ? escape(name) : "#{escape(name)}=#{escape(value)}")
       end
       parts.join("&")
     end
 
-    # 1つのキーと値をargvの断片へ変換する。
+    # Convert one key and value into an argv fragment.
     #
     #   page_size: "A4"     → ["--page-size", "A4"]
     #   grayscale: true     → ["--grayscale"]
@@ -69,8 +67,8 @@ module Sghtmltopdf
       pairs_for(key, value).flat_map { |name, arg| arg.nil? ? ["--#{name}"] : ["--#{name}", arg] }
     end
 
-    # 1つのキーと値を「フラグ名と値」のペアの列にする。値が`nil`のペアは
-    # 値を取らないフラグ(`--toc`など)。
+    # Turn one key and value into a list of "flag name and value" pairs. A pair whose value is
+    # `nil` is a flag taking no value (`--toc` and the like).
     def pairs_for(key, value)
       name = flag_name(key)
       return font_pairs(value) if name == "font"
@@ -78,26 +76,25 @@ module Sghtmltopdf
       case value
       when nil, false then []
       when true then [[name, nil]]
-      # 配列は同じオプションの繰り返し。要素ごとに同じ規則を適用する。
+      # An array means the same option repeated. The same rule applies to each element.
       when Array then value.flat_map { |element| pairs_for(key, element) }
       when Hash
-        # wicked_pdfの`margin: {top: 10}`のような入れ子は受けない。対応する
-        # CLIフラグが無く、機械的に平坦化すると綴り違いのキーまで黙って
-        # 通ってしまう。移行時は移行ガイドの対応表を見て書き換えてもらう。
-        # なお単位を省いた数値の解釈はwicked_pdfと同じくmm(`cli/units.rs`)。
+        # Nesting such as wicked_pdf's `margin: {top: 10}` is not accepted. There is no
+        # corresponding CLI flag, and flattening it mechanically would let even misspelled
+        # keys through silently. When migrating, use the correspondence table in the
+        # migration guide to rewrite them. A unitless number is read as mm, as in wicked_pdf (`cli/units.rs`).
         example = value.keys.first
         raise ArgumentError,
-          "#{key}にHashは渡せません(pathとindexを取るのは:fontだけです)。" \
-          "入れ子のオプションは平坦なキーで指定してください" \
-          "#{": 例 #{key}_#{example}: \"…\"" if example}"
+          "a Hash cannot be passed for #{key} (only :font takes a path and an index). " \
+          "Give nested options as flat keys" \
+          "#{": for example #{key}_#{example}: \"...\"" if example}"
       else [[name, value.to_s]]
       end
     end
 
-    # `--font`と`--font-index`は出現順で対応付けられる(CLIは
-    # `ArgMatches#indices_of`で「`--font-index`より手前にある最後の`--font`」
-    # へ結び付ける)。そのため、フェイス番号は
-    # 必ず対応する`--font`の直後へ置く。
+    # `--font` and `--font-index` are paired by their order of appearance (the CLI ties each
+    # `--font-index` to "the last `--font` before it" via `ArgMatches#indices_of`).
+    # So a face index always goes immediately after its own `--font`.
     #
     #   font: "a.ttf"                        → ["--font", "a.ttf"]
     #   font: {path: "a.ttc", index: 1}      → ["--font", "a.ttc", "--font-index", "1"]
@@ -113,7 +110,7 @@ module Sghtmltopdf
       when Array then value.flat_map { |element| font_pairs(element) }
       when Hash
         path = value[:path] || value["path"]
-        raise ArgumentError, "fontのHashにはpathが必要です: #{value.inspect}" if path.nil?
+        raise ArgumentError, "a font Hash needs a path: #{value.inspect}" if path.nil?
 
         index = value[:index] || value["index"]
         pairs = [["font", path.to_s]]
@@ -123,12 +120,12 @@ module Sghtmltopdf
       end
     end
 
-    # `:page_size` → `page-size`。
+    # `:page_size` becomes `page-size`.
     def flag_name(key)
       key.to_s.tr("_", "-")
     end
 
-    # 変換オプションだけを、渡された順にペアとして列挙する。
+    # Enumerate only the conversion options, as pairs, in the order they were given.
     def each_pair(options, &block)
       options.each do |key, value|
         key = canonical_key(key)

data/lib/sghtmltopdf/railtie.rb

@@ -28,12 +28,12 @@ module Sghtmltopdf
       defaults
     end
 
-    # 読むのはinitializerの中ではなく`after_initialize`。パイプラインが
-    # `config.assets.paths`を埋めるのは自分のinitializer(Propshaftなら
-    # `propshaft.append_assets_path`)で、そちらの方が後に走るため。
+    # Read in `after_initialize`, not inside the initializer. The pipeline fills
+    # `config.assets.paths` in its own initializer (for Propshaft,
+    # `propshaft.append_assets_path`), and that one runs later.
     #
-    # `config/initializers`より後になるが、`apply_defaults`は明示的に設定した
-    # 値より常に弱いので、ユーザーの設定を踏むことはない。
+    # This runs after `config/initializers`, but `apply_defaults` is always
+    # weaker than explicitly set values, so it never overrides user settings.
     initializer "sghtmltopdf.defaults" do |app|
       app.config.after_initialize do
         Sghtmltopdf.config.apply_defaults(Sghtmltopdf::Railtie.default_options(app))