sghtmltopdf 0.4.0-aarch64-linux → 0.5.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a44aaf047687b49c64558bc29dbf047c625708e484e1f78771f8dcf2e1d594bc
-  data.tar.gz: bf7dd74950f85a78df6bdc8c888319f890250bdd908acf4f3e90bcf9a72a63dc
+  metadata.gz: 35fd52de515952053bbd3f16b2b8bc8b06a1271afbfa70ef7968d8c71e3e0831
+  data.tar.gz: 5edee4a9f35c7997f572d74faf106046b16d8f92b0c47f8527a0d78c289e1b58
 SHA512:
-  metadata.gz: 520dafa89a98b182ccb51784157ce8c19126c62ca2a22e80ebd065860a941ac4f17821572ab66be5938a427ef467499f7959df230c016621acb9924db5ee7e6f
-  data.tar.gz: 54dd99c0f46f42d4399ca8717161ebdb63e5caf39716e7240c350a9a34430c918225f9d1717a04df429476e3f8bca1c92857d5505e3bd263305b78725bde34b1
+  metadata.gz: b215282c4ba6e4a67c40f04bf5ee4ae7d1aa67528e4e044b10ba359c237fb93114acea7884775acf86aaa36ffe2b89ff103522858b6cc719918eace286906534
+  data.tar.gz: 3c578b24199edb331c9d8bc117f75fc7c779e77da2929596d3c35d72fa771217d4c1b57a4859086624b4424ac49422293560ebdb99a364ee11e695a8b015eb15

data/README.md

@@ -13,10 +13,10 @@ The engine runs inside your process through a native extension (magnus + rb-sys)
 gem "sghtmltopdf"
 ```
 
-Precompiled native gems are published for `x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, and `arm64-darwin`.
+Precompiled native gems are published for `x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`, and `x86_64-darwin`.
 There is no build step on those platforms.
 
-Elsewhere (Intel Mac, Windows) the gem cannot run in-process — the source gem does not carry the Rust core and will refuse to build with an explanatory message.
+Elsewhere (Windows) the gem cannot run in-process — the source gem does not carry the Rust core and will refuse to build with an explanatory message.
 Point those environments at a separate `sghtmltopdf server` process instead; see [Delegating to a server](#delegating-to-a-server).
 
 Requires Ruby >= 3.2.
@@ -38,6 +38,31 @@ Sghtmltopdf.render_to_file(html, "invoice.pdf", page_size: "A4")
 Sghtmltopdf.render(html) { |bytes| io.write(bytes) }
 ```
 
+## Header and footer HTML
+
+Pass markup directly without creating temporary files:
+
+```ruby
+Sghtmltopdf.render(html,
+  header_html_content: '<div>Invoice [title]</div>',
+  footer_html_content: '<div>Page [page] of [topage]</div>')
+```
+
+These options work with `render`, block output, `render_to_file`, global
+configuration, and server delegation. The shared CLI options are
+`--header-html-content` and `--footer-html-content`.
+
+`header_html` and `footer_html` still accept file paths. Supplying both a path
+and content for the same side raises `Sghtmltopdf::UsageError`, including when
+one comes from global configuration. `nil` or `false` disables a configured
+option; an empty string is an explicitly empty header or footer. Either HTML
+form takes precedence over simple text options for that side.
+
+Content uses the same placeholder expansion and margin clipping as file input.
+Embedded `data:` images are supported; external resources remain blocked.
+With server delegation, markup travels in URL query parameters, so URL length
+limits may apply and request logs may contain the markup.
+
 ## Rails
 
 Adding the gem is enough; the Railtie wires everything up, and nothing is loaded when Rails is absent.

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))

data/lib/sghtmltopdf/renderer.rb

@@ -1,25 +1,25 @@
 # frozen_string_literal: true
 
 module Sghtmltopdf
-  # `render pdf: "invoice"`のオプションを、
+  # Sorts the options of `render pdf: "invoice"` into three groups:
   #
-  # * Railsのビュー描画(`render_to_string`)へ渡すもの
-  # * レスポンスの組み立て(`send_data`)へ渡すもの
-  # * PDF変換(`Sghtmltopdf.render`)へ渡すもの
+  # * those passed to Rails view rendering (`render_to_string`)
+  # * those passed to building the response (`send_data`)
+  # * those passed to PDF conversion (`Sghtmltopdf.render`)
   #
-  # の3つに振り分ける。
-  # Railsに依存しないpure Rubyのクラスなので、Rails無しでも単体テストできる。
+  #
+  # It is a pure Ruby class with no dependency on Rails, so it can be unit tested without Rails.
   class Renderer
-    # `render_to_string`へそのまま渡すキー。
+    # The keys passed straight to `render_to_string`.
     RAILS_RENDER_KEYS = %i[
       action assigns body collection file formats handlers html inline layout
       locals object partial plain prefixes template variants
     ].freeze
 
-    # レスポンスの組み立てに使うキー(`send_data`へ渡す)。
+    # The keys used to build the response (passed to `send_data`).
     RESPONSE_KEYS = %i[disposition filename status].freeze
 
-    # レンダラ自身が解釈するキー(PDFにせずHTMLのまま返すデバッグ用)。
+    # The keys the renderer itself interprets (for debugging: return the HTML rather than a PDF).
     RENDERER_KEYS = %i[show_as_html].freeze
 
     PDF_CONTENT_TYPE = "application/pdf"
@@ -27,17 +27,17 @@ module Sghtmltopdf
 
     attr_reader :name, :options
 
-    # @param name [String, Symbol, nil] `pdf:`に渡された値(ファイル名の素)
-    # @param options [Hash] `render`に渡されたその他のオプション
-    # @param default_name [String, nil] `name`が空のときのファイル名
-    #   (コントローラの`action_name`を想定)
+    # @param name [String, Symbol, nil] the value given to `pdf:` (the basis of the file name)
+    # @param options [Hash] the other options given to `render`
+    # @param default_name [String, nil] the file name when `name` is empty
+    #   (the controller's `action_name` is expected)
     def initialize(name, options = {}, default_name: nil)
       @name = blank?(name) ? (default_name || "document").to_s : name.to_s
       @options = options.to_h { |key, value| [key.to_sym, value] }
     end
 
-    # `ActionController::Renderers.add(:pdf)`でレンダラを登録する。
-    # RailtieのAction Controller読み込みフック(`on_load`)から呼ぶ。
+    # Register the renderer with `ActionController::Renderers.add(:pdf)`.
+    # Called from the Railtie's Action Controller load hook (`on_load`).
     def self.register!
       ::ActionController::Renderers.add(:pdf) do |name, options|
         renderer = ::Sghtmltopdf::Renderer.new(name, options, default_name: action_name)
@@ -46,18 +46,18 @@ module Sghtmltopdf
       end
     end
 
-    # ビューの描画に使うオプション。
+    # The options used to render the view.
     def render_options
       options.select { |key, _| RAILS_RENDER_KEYS.include?(key) }
     end
 
-    # PDF変換に使うオプション。
+    # The options used for the PDF conversion.
     def convert_options
       known = RAILS_RENDER_KEYS + RESPONSE_KEYS + RENDERER_KEYS
       options.reject { |key, _| known.include?(key) }
     end
 
-    # 描画したHTMLをレスポンスの本文へ変換する。
+    # Turn the rendered HTML into the response body.
     def body_for(html)
       show_as_html? ? html : Sghtmltopdf.render(html, **convert_options)
     end
@@ -73,19 +73,19 @@ module Sghtmltopdf
       show_as_html? ? HTML_CONTENT_TYPE : PDF_CONTENT_TYPE
     end
 
-    # `filename: "x.pdf"` > `pdf: "x"` の順。拡張子は二重に付けない。
+    # `filename: "x.pdf"` wins over `pdf: "x"`. The extension is not doubled up.
     def filename
       base = blank?(options[:filename]) ? name : options[:filename].to_s
       base.downcase.end_with?(".pdf") ? base : "#{base}.pdf"
     end
 
-    # wicked_pdfと同じく既定は`inline`(ブラウザ内で開く)。
+    # The default is `inline` (opened in the browser), as in wicked_pdf.
     def disposition
       blank?(options[:disposition]) ? "inline" : options[:disposition].to_s
     end
 
-    # wicked_pdfの`show_as_html`相当。PDFにせずHTMLをそのまま返すので、
-    # ブラウザの開発者ツールでレイアウトを確認できる。
+    # The equivalent of wicked_pdf's `show_as_html`. It returns the HTML rather than a PDF, so
+    # the layout can be inspected in the browser's developer tools.
     def show_as_html?
       value = options[:show_as_html]
       !(value.nil? || value == false || value == "false")

data/lib/sghtmltopdf/server_client.rb

@@ -6,7 +6,7 @@ require "uri"
 module Sghtmltopdf
   class ServerError < Error; end
 
-  # HTTPサーバモード(`sghtmltopdf server`)へ変換を委譲するクライアント。
+  # The client delegating conversion to HTTP server mode (`sghtmltopdf server`).
   #
   #   Sghtmltopdf.configure { |c| c.server_url = "http://pdf.internal:8080" }
   #   pdf = Sghtmltopdf.render(html, page_size: "A4")
@@ -14,29 +14,28 @@ module Sghtmltopdf
     DEFAULT_OPEN_TIMEOUT = 5
     DEFAULT_READ_TIMEOUT = 120
 
-    # 一度に読むチャンクの目安。`?stream=1`のときはこの単位でブロックへ渡る。
+    # The rough size of each read. With `?stream=1` this is the unit handed to the block.
     CHUNK_SIZE = 64 * 1024
 
     attr_reader :uri, :open_timeout, :read_timeout
 
-    # @param url [String] サーバのベースURL(`http://host:port`)
+    # @param url [String] the server's base URL (`http://host:port`)
     def initialize(url, open_timeout: nil, read_timeout: nil)
       @uri = parse(url)
       @open_timeout = (open_timeout || DEFAULT_OPEN_TIMEOUT).to_f
       @read_timeout = (read_timeout || DEFAULT_READ_TIMEOUT).to_f
     end
 
-    # HTMLをPDFへ変換する。
+    # Convert HTML to PDF.
     #
-    # ブロックを渡すと`?stream=1`(chunked transfer encoding)を使い、
-    # サーバがページを確定したそばからチャンクを渡す。ブロックが無ければ
-    # PDF全体をStringで返す。
+    # Given a block it uses `?stream=1` (chunked transfer encoding) and hands over chunks as
+    # the server settles each page. With no block it returns the whole PDF as a String.
     def render(html, options, &block)
       request = build_request(html, options, stream: !block.nil?)
       pdf = nil
       start do |http|
-        # `request`はブロック付きだとレスポンスオブジェクトを返すので、
-        # 結果は外の変数で受ける。
+        # With a block, `request` returns the response object, so the result is received in an
+        # outer variable.
         http.request(request) do |response|
           ensure_success!(response)
           if block
@@ -49,9 +48,9 @@ module Sghtmltopdf
       pdf
     end
 
-    # 変換結果を`path`へ書き出す。途中で失敗しても壊れたPDFを残さないよう、
-    # 一時ファイルへ書いてからrenameする(ネイティブ拡張の`FileSink`と同じ
-    # 挙動に揃えている)。
+    # Write the conversion result to `path`. To leave no broken PDF on a failure part-way
+    # through, it writes to a temporary file and renames (matching the behaviour of the
+    # native extension's `FileSink`).
     def render_to_file(html, options, path)
       tmp = "#{path}.#{Process.pid}.tmp"
       begin
@@ -60,7 +59,7 @@ module Sghtmltopdf
         end
       rescue SystemCallError => e
         File.unlink(tmp) if File.exist?(tmp)
-        raise InputError, "#{path}への書き出しに失敗しました: #{e.message}"
+        raise InputError, "failed to write to #{path}: #{e.message}"
       rescue StandardError
         File.unlink(tmp) if File.exist?(tmp)
         raise
@@ -74,7 +73,7 @@ module Sghtmltopdf
     def parse(url)
       uri = URI.parse(url.to_s)
       unless uri.is_a?(URI::HTTP) && uri.host
-        raise ArgumentError, "server_urlにはhttp(s)のURLを指定してください: #{url.inspect}"
+        raise ArgumentError, "server_url must be an http(s) URL: #{url.inspect}"
       end
 
       uri
@@ -102,12 +101,12 @@ module Sghtmltopdf
         &block
       )
     rescue Net::OpenTimeout, Net::ReadTimeout => e
-      raise ServerError, "#{base}への接続がタイムアウトしました: #{e.class}"
+      raise ServerError, "the connection to #{base} timed out: #{e.class}"
     rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
-      raise ServerError, "#{base}への接続に失敗しました: #{e.message}"
+      raise ServerError, "the connection to #{base} failed: #{e.message}"
     end
 
-    # エラー応答の本文は`text/plain`の日本語メッセージ(CLIと同じ文言)。
+    # An error response's body is a `text/plain` message (the same wording as the CLI).
     def ensure_success!(response)
       return if response.is_a?(Net::HTTPOK)
 
@@ -120,8 +119,8 @@ module Sghtmltopdf
       when 400 then UsageError
       when 413 then InputError
       when 500 then RenderError
-      # 404/405はパスやメソッドの間違い＝相手がsghtmltopdfのサーバでない
-      # 可能性が高い。503/504はキュー溢れ・キュー待ちのタイムアウト。
+      # A 404 or 405 means a wrong path or method, most likely because the other end is not
+      # an sghtmltopdf server. A 503 or 504 means the queue overflowed or the queue wait timed out.
       else ServerError
       end
     end

data/lib/sghtmltopdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sghtmltopdf
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/sghtmltopdf.rb

@@ -5,9 +5,9 @@ require_relative "sghtmltopdf/options"
 require_relative "sghtmltopdf/configuration"
 require_relative "sghtmltopdf/renderer"
 
-# precompiled gemはRubyのマイナーバージョンごとのディレクトリへ`.so`を置く
-# (rake-compilerのクロスビルドの慣習)。開発中の`rake compile`は
-# `lib/sghtmltopdf/sghtmltopdf.so`に置くので、両方を試す。
+# A precompiled gem puts the `.so` in a directory per Ruby minor version
+# (rake-compiler's cross-build convention). During development `rake compile` puts it in
+# `lib/sghtmltopdf/sghtmltopdf.so`, so both are tried.
 begin
   RUBY_VERSION =~ /(\d+\.\d+)/
   require "sghtmltopdf/#{Regexp.last_match(1)}/sghtmltopdf"
@@ -15,37 +15,36 @@ rescue LoadError
   require "sghtmltopdf/sghtmltopdf"
 end
 
-# `Error`(ネイティブ拡張が定義)を継承するため、拡張の読み込みより後に書く。
+# It inherits `Error` (defined by the native extension), so it comes after the extension is loaded.
 require_relative "sghtmltopdf/server_client"
 
 module Sghtmltopdf
-  # ブロック付き`render`で1回に渡すバイト数の目安(ローカル変換のみ)。
-  # ページ確定ごとにブロックを呼ぶとGVLの取り直しが増えるため、ここまで
-  # 溜めてから渡す。
+  # The rough number of bytes handed over per call to a block-taking `render` (local conversion only).
+  # Calling the block on every settled page would mean reacquiring the GVL too often, so this
+  # much is accumulated first.
   DEFAULT_CHUNK_SIZE = 64 * 1024
 
   class << self
-    # HTMLを変換してPDFのバイト列(ASCII-8BITのString)を返す。
+    # Convert HTML and return the PDF bytes (an ASCII-8BIT String).
     #
-    # ブロックを渡すと、PDF全体を組み立ててから返す代わりにチャンクごとに
-    # ブロックを呼ぶ(返り値はnil)。Rackの`response.stream`へ流したり、S3の
-    # マルチパートアップロードへ繋いだりするための口(エンジン側は出力先(sink)
-    # を意識しない設計に対応する)。
+    # Given a block, it calls the block per chunk rather than assembling the whole PDF first
+    # (returning nil). It is the hook for streaming into Rack's `response.stream` or into an
+    # S3 multipart upload (matching the engine's design, which is unaware of the output sink).
     #
     #   Sghtmltopdf.render(html) { |bytes| response.stream.write(bytes) }
     #
-    # ローカル・サーバ委譲のどちらでも、PDF全体が組み上がるのを待たずに
-    # 書き出せる(ローカルは確定したページから順に、サーバは`?stream=1`の
-    # chunked transfer encodingをそのまま渡す)。
+    # Both locally and when delegating to a server, it can be written out without waiting for
+    # the whole PDF to be assembled (locally page by page as they settle; from a server, the
+    # `?stream=1` chunked transfer encoding passed straight through).
     #
-    # ただし逐次になるのはPDFの書き出しだけで、HTMLのパースとレイアウトは
-    # 文書全体に対して先に行う。最初のチャンクが届くのは変換の終盤で、
-    # ピークメモリもブロック無しの場合と変わらない。HTMLを読みながら
-    # ページを確定させたい場合は`streaming: true`と併せて使う
-    # (制約と引き換えにメモリが大きく減る)。
+    # Only the PDF writing is incremental, though: HTML parsing and layout still happen for
+    # the whole document first. The first chunk arrives late in the conversion, and the peak
+    # memory is no different from the block-less case. To settle pages while the HTML is being
+    # read, use it together with `streaming: true`
+    # (which trades constraints for a large reduction in memory).
     #
-    # 1回に渡すバイト数の目安は`chunk_size:`で変えられる(既定64KiB。
-    # ローカル変換のみ。小さくするとGVLの取り直しが増える)。
+    # The rough bytes per call can be changed with `chunk_size:` (64KiB by default; local
+    # conversion only; a smaller value means reacquiring the GVL more often).
     def render(html, **options, &block)
       options = Options.canonicalize(options)
       client = server_client(options)
@@ -56,10 +55,10 @@ module Sghtmltopdf
       nil
     end
 
-    # HTMLを変換して`path`へ書き出す。
+    # Convert HTML and write it to `path`.
     #
-    # 一時ファイルへ書いて成功時だけrenameするため、途中で失敗しても
-    # 壊れたPDFが出力先に残らない(サーバへ委譲する場合も同じ)。
+    # It writes to a temporary file and renames only on success, so a failure part-way through
+    # leaves no broken PDF at the destination (the same when delegating to a server).
     def render_to_file(html, path, **options)
       options = Options.canonicalize(options)
       client = server_client(options)
@@ -69,7 +68,7 @@ module Sghtmltopdf
       nil
     end
 
-    # グローバルな既定オプション。
+    # The global default options.
     def configure
       yield config
       config
@@ -79,19 +78,19 @@ module Sghtmltopdf
       @config ||= Configuration.new
     end
 
-    # 主にテスト用。設定を空に戻す。
+    # Mainly for tests. Resets the configuration to empty.
     def reset_config!
       @config = Configuration.new
     end
 
     private
 
-    # グローバル設定 → 呼び出し時オプションの順にマージしてargvにする。
+    # Merge in the order global settings, then call-time options, and turn that into argv.
     def argv_for(options)
       Options.to_argv(config.to_h.merge(options))
     end
 
-    # `server_url`があればサーバへ委譲する。タイムアウトも同じ順でマージする。
+    # With a `server_url` it delegates to the server. The timeout merges in the same order.
     def server_client(options)
       merged = config.to_h.merge(options)
       url = merged[:server_url]
@@ -104,16 +103,16 @@ module Sghtmltopdf
       )
     end
 
-    # ブロックへ1回に渡すバイト数の目安(ローカル変換のみ)。
+    # The rough bytes handed to the block per call (local conversion only).
     def chunk_size(options)
       value = config.to_h.merge(options)[:chunk_size]
       value.nil? ? DEFAULT_CHUNK_SIZE : Integer(value)
     end
 
-    # サーバへ渡すオプション。流し込まれた既定値は外す
-    # (Rails向けの`base_url`・`allow`はローカルのファイル解決のための
-    # 既定値で、サーバモードではリクエストから指定できず400になる。
-    # 明示的に設定した値はそのまま送り、可否はサーバに判断させる)。
+    # The options passed to the server. The injected defaults are removed
+    # (the Rails-oriented `base_url` and `allow` are defaults for local file resolution, and
+    # server mode cannot take them from a request, giving a 400.
+    # An explicitly set value is sent as-is and the server decides whether to accept it).
     def server_options(options)
       config.to_h(with_defaults: false).merge(options)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sghtmltopdf
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: aarch64-linux
 authors:
 - yo_waka
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   Ruby binding for sghtmltopdf, a successor to wkhtmltopdf: an HTML-to-PDF