howdoc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02cc27d9848b0932cc7ba10c66b8e5682c955071f2cde03f27e6c9061c52d82c
-  data.tar.gz: 1bed4d6da3860c0ea8ac1f3f680218f24941f45fbb7d8e3b0699085e70588811
+  metadata.gz: 3c4cdda2ccd66b3c800f8711f0ea76b5220bee90496b337bccb15d1478b078b0
+  data.tar.gz: 7c2252c5adce29342f4483f3cf6529d8a9fd3f009e6b6e92747e408110d173ba
 SHA512:
-  metadata.gz: 72e52519fec7d24abdb8765aa146702ef053a627fd87e4b40e1ff77775ba69ed626db5250accbb307719bbfee68a7f12e8d1fac6d966a0ab05df9859a1b38326
-  data.tar.gz: 70208bdc3b1557985b69bbdceb70ade90a91c39b9063412ed922df7cd1cae26e5629875dd1f66a16277364af39d49eff10ede8df80695c678a1792675f0f0b42
+  metadata.gz: fa0d4d38e5ee59ad0b05acd8e9db25f87e99024b9c62fd7eff1b8139a1b83712a75c68e3f540c82393658fd3febd451bf420c33bea5e69e7e6c446079574e3cf
+  data.tar.gz: 7e5147574f8c072a49e31d6f2ce9c001606f63d90604f1e7e9bc9a51257ce08ce2ae943449df76d0dbc84413766ecd58869c507a3f8c11ad32259b9a526748bf

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.0
+
+Guides are now written in every language the application publishes, from a
+single test run. Previously a run produced guides in the language the suite
+happened to be running in, and the other languages were silently left behind.
+
+- `config.locales` names the languages every guide is written in, not only the
+  languages an index is built for.
+- A step is recorded as an action and its values rather than as a finished
+  sentence, and narrated once per language when the guide is written.
+- Screenshots are taken once and copied into each language's guide.
+- A guide's own heading and introduction can be translated under
+  `howdoc.documents.<permalink>`, since they come from the test rather than
+  from the engine.
+- `Howdoc::Narrator.field` defers a field label until the language is known.
+  `Howdoc.start(locale:)` still pins a guide to one language.
+- Untranslated keys are reported with the language they are missing from.
+
 ## 0.1.0
 
 First release. Extracted from a working in-house documentation helper that had

data/README.md

@@ -45,6 +45,7 @@ Howdoc.configure do |config|
   config.enabled = ENV['DOC'].present?    # off unless asked for
   config.host    = 'example.com'          # the address a reader should open
   config.formats = %i[html]
+  config.locales = %i[en et]              # languages every guide is written in
 
   config.register_locale_path 'test/howdoc/locales/*.yml'
   config.register_template_path 'test/howdoc/templates'
@@ -70,8 +71,7 @@ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
       id: metadata[:doc],
       permalink: metadata[:permalink],
       intro: metadata[:intro],
-      title: "How to #{metadata[:description]}?",
-      locale: I18n.locale
+      title: "How to #{metadata[:description]}?"
     )
   end
 
@@ -137,6 +137,52 @@ Three actions come translated even though no wrapper records them, because
 almost every suite ends up writing a helper that needs one: `menu` (a `path`),
 `fill_in_editor` (a `value`) and `sign_in_required` (a `text`).
 
+## Languages
+
+A test runs in one language. Its guide is written in all of them.
+
+Name the languages your application publishes and every recorded guide is
+written once per language, from the same run:
+
+```ruby
+config.locales = %i[en et]
+```
+
+```
+public/docs/en/how_to_add_a_claim.html
+public/docs/et/how_to_add_a_claim.html
+```
+
+Nothing is recorded as a finished sentence, which is what makes this possible:
+a step is kept as the action and the values it happened with, and the sentence
+is composed once per language when the page is written. The screenshot is taken
+once, while the browser is still on the page, and copied into each language's
+guide -- it is a picture of the same application either way.
+
+A guide's own heading is the exception, because it comes from the test rather
+than from the engine. Translate `howdoc.documents.<permalink>.title` to give the
+same guide a heading in another language, and `.intro` for its introduction:
+
+```yaml
+et:
+  howdoc:
+    documents:
+      how_to_add_a_claim:
+        title: Kuidas lisada nõue?
+```
+
+Left untranslated, every language gets the heading the test gave it. A guide
+that belongs to one language only -- something only that language's users ever
+see -- says so: `Howdoc.start(..., locale: :et)`.
+
+A value that reads differently in different languages must not be resolved
+while the test runs, or it freezes into the language the test ran in. Field
+labels are the usual case, and `Howdoc::Narrator.field` defers one:
+
+```ruby
+Howdoc.record(:check, field: Howdoc::Narrator.field(locator))
+```
+
 ## Wording
 
 Every sentence is an I18n key under `howdoc.actions`, so the engine contains no
@@ -161,8 +207,10 @@ own by translating `howdoc.fields.<locator>`, or replace the whole convention:
 config.field_label { |locator| MyLabels.for(locator) }
 ```
 
-Any key that is used but not translated is reported at the end of the run rather
-than leaving a silent hole in the guide.
+Any key that is used but not translated is reported at the end of the run,
+naming the language it is missing from, rather than leaving a silent hole in the
+guide. A step no language can describe is not recorded at all; a step one
+language cannot describe is left out of that language's guide only.
 
 ## Templates
 

data/lib/howdoc/capybara_actions.rb

@@ -29,9 +29,8 @@ module Howdoc
 
     def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
       doc = Howdoc.extract_options!(options)
-      label = howdoc_field_label(locator)
 
-      narrate(fill_in_action(label), doc, field: label, value: with)
+      narrate(fill_in_action(locator), doc, field: howdoc_field_label(locator), value: with)
 
       super(locator, with:, currently_with:, fill_options:, **options)
     end
@@ -114,16 +113,18 @@ module Howdoc
 
     private
 
+    # Not the label itself: a guide is written in every language the
+    # application publishes, and what a reader calls a field is a translation,
+    # so the label is settled once per language when the page is written.
     def howdoc_field_label(locator)
-      Howdoc::Narrator.field_label(locator, locale: howdoc_locale)
+      Howdoc::Narrator.field(locator)
     end
 
-    def howdoc_locale
-      Howdoc.current&.locale || I18n.locale
-    end
-
-    def fill_in_action(label)
-      case label.to_s
+    # Which sentence a fill_in gets is decided from the field's own name rather
+    # than from its label, because the name is the same in every language and
+    # the choice must be too.
+    def fill_in_action(locator)
+      case Howdoc.config.field_label.call(locator).to_s
       when 'email' then :fill_in_email
       when 'password' then :fill_in_password
       else :fill_in

data/lib/howdoc/configuration.rb

@@ -22,10 +22,13 @@ module Howdoc
     # Writers to run for every finished document, in order.
     attr_accessor :formats
 
-    # Locales to build an index for. Left nil, only the locales that actually
-    # produced a guide get one, which means a run in a single language quietly
-    # drops the other languages' indexes. Naming them keeps every index in
-    # place, empty ones included.
+    # The languages the application publishes its guides in. A test runs in one
+    # language, but every guide it records is written in all of these, so a
+    # second language costs a translation file rather than a second test run.
+    #
+    # These are also the locales an index is built for. Left nil, a guide is
+    # written only in the language the suite is running in, and only the
+    # locales that actually produced a guide get an index.
     attr_accessor :locales
 
     # Screenshots are taken at this height unless the step asked for a full

data/lib/howdoc/document.rb

@@ -4,6 +4,11 @@ module Howdoc
   # One guide: the identity a test gave it, plus the steps recorded while that
   # test ran. A document collects everything in memory and is written out once,
   # so a writer always sees the whole guide rather than a half-built page.
+  #
+  # A test runs in one language but a guide is published in all of them, so a
+  # document holds nothing that a language would change. Every such thing --
+  # the heading, the sentences, the file name -- belongs to an Edition, and a
+  # document has one per language.
   class Document
     # Letters that carry no accent to strip: they are their own character, so
     # Unicode decomposition leaves them untouched and a filename filter would
@@ -13,24 +18,44 @@ module Howdoc
       'đ' => 'd', 'ð' => 'd', 'ł' => 'l', 'þ' => 'th'
     }.freeze
 
-    attr_reader :id, :permalink, :title, :intro, :locale, :steps
+    attr_reader :id, :permalink, :steps, :locales
 
-    def initialize(id:, title:, locale:, permalink: nil, intro: nil)
+    # +title+ and +intro+ are whatever the test knew: a string in the language
+    # it was written in, or a hash keyed by locale when the test itself knows
+    # more than one. Either way a translation under howdoc.documents wins, so a
+    # guide gets a heading in a language no test speaks.
+    def initialize(id:, title:, locales:, permalink: nil, intro: nil)
       @id = id
       @title = title
-      @locale = locale.to_sym
-      @permalink = permalink
       @intro = intro
+      @permalink = permalink
+      @locales = Array(locales).map(&:to_sym)
       @steps = []
       @counter = 0
     end
 
-    def slug
-      @slug ||= (permalink || slugify(title)).to_s
+    def editions
+      @editions ||= locales.map { |locale| Edition.new(self, locale) }
+    end
+
+    # The edition a test is recording into. Screenshots are taken while the
+    # browser is still on the page, long before the other editions are written,
+    # so they are saved where this one keeps its pictures and copied across when
+    # the guides are written.
+    def primary
+      editions.first
+    end
+
+    def locale
+      primary.locale
     end
 
-    def heading
-      id.nil? ? title : "#{id}. #{title}"
+    def title_for(locale)
+      Narrator.document_text(:title, key: translation_key, locale:, default: in_locale(@title, locale))
+    end
+
+    def intro_for(locale)
+      Narrator.document_text(:intro, key: translation_key, locale:, default: in_locale(@intro, locale))
     end
 
     def new_step(**attributes)
@@ -44,23 +69,14 @@ module Howdoc
       steps.last
     end
 
-    def dir
-      File.join(Howdoc.config.root, locale.to_s)
-    end
-
-    def image_dir
-      File.join(dir, 'images')
-    end
-
-    def path(extension)
-      File.join(dir, "#{slug}.#{extension}")
-    end
-
-    def image_filename(number)
-      "#{slug}_#{number}.png"
-    end
-
-    private
+    # What the recording edition answers, asked of the document itself, because
+    # that is what a recorder has in its hand.
+    def slug = primary.slug
+    def heading = primary.heading
+    def dir = primary.dir
+    def image_dir = primary.image_dir
+    def path(extension) = primary.path(extension)
+    def image_filename(number) = primary.image_filename(number)
 
     # Deliberately not ActiveSupport's parameterize: the engine has no business
     # dragging Rails into a project that only wanted a documentation generator.
@@ -68,7 +84,7 @@ module Howdoc
     # Accents are decomposed and their marks dropped rather than deleted whole,
     # so an Estonian title turns into "kuidas_lisada_noue" instead of the
     # unreadable "kuidas_lisada_n_ue" a plain ASCII filter would leave behind.
-    def slugify(string)
+    def self.slugify(string)
       string
         .to_s
         .downcase
@@ -79,5 +95,20 @@ module Howdoc
         .gsub(/[^a-z0-9]+/, '_')
         .gsub(/\A_+|_+\z/, '')
     end
+
+    private
+
+    # The name a translation of this guide's own words is filed under. A
+    # permalink is the obvious one; without it the untranslated title has to do,
+    # since it is the only stable thing a test gave us.
+    def translation_key
+      @translation_key ||= (permalink || self.class.slugify(in_locale(@title, locales.first))).to_s
+    end
+
+    def in_locale(value, locale)
+      return value unless value.is_a?(Hash)
+
+      value[locale.to_sym] || value[locale.to_s] || value.values.first
+    end
   end
 end

data/lib/howdoc/edition.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # One language's version of a guide.
+  #
+  # A guide is recorded once -- the same clicks, the same screenshots -- and
+  # written out once per language. Everything that differs between those
+  # versions is here: the heading, the sentences, the directory the page lands
+  # in and the names of the pictures in it. A template is handed the edition for
+  # the language being written, so nothing in a template has to know that a
+  # second language exists.
+  class Edition
+    attr_reader :document, :locale
+
+    def initialize(document, locale)
+      @document = document
+      @locale = locale.to_sym
+    end
+
+    def id
+      document.id
+    end
+
+    def permalink
+      document.permalink
+    end
+
+    def title
+      @title ||= document.title_for(locale)
+    end
+
+    def intro
+      @intro ||= document.intro_for(locale)
+    end
+
+    def heading
+      id.nil? ? title : "#{id}. #{title}"
+    end
+
+    # A permalink is the same in every language, so the guides sit beside each
+    # other under one name. Without one the file is named after the heading,
+    # which means a translated heading gives a translated file name.
+    def slug
+      @slug ||= (permalink || Document.slugify(title)).to_s
+    end
+
+    def steps
+      @steps ||= document.steps.map { |step| step.narrate(self) }
+    end
+
+    def dir
+      File.join(Howdoc.config.root, locale.to_s)
+    end
+
+    def image_dir
+      File.join(dir, 'images')
+    end
+
+    def path(extension)
+      File.join(dir, "#{slug}.#{extension}")
+    end
+
+    def image_filename(number)
+      "#{slug}_#{number}.png"
+    end
+  end
+end

data/lib/howdoc/narrator.rb

@@ -7,12 +7,30 @@ module Howdoc
   # sentence itself -- every one of them is an I18n key, so the vocabulary is
   # translatable and an application can reword any instruction without touching
   # the code that records it.
+  #
+  # Nothing here is settled while a test runs. A guide is recorded once and
+  # written out in every language it is published in, so a sentence is composed
+  # at writing time, once per language.
   module Narrator
-    SCOPE = 'howdoc.actions'
+    ROOT = 'howdoc'
+    ACTIONS = :actions
+    FIELDS = :fields
+    DOCUMENTS = :documents
+
+    # A value that cannot be settled until the language is known. A form field
+    # is the usual case: what a reader calls it is a translation, so recording
+    # the resolved label would freeze the guide into the language the test
+    # happened to run in.
+    Field = Struct.new(:locator) do
+      def to_howdoc_text(locale)
+        Narrator.field_label(locator, locale:)
+      end
+    end
 
     class << self
       # Keys that were asked for but not translated, reported once at the end of
-      # a run rather than silently producing a guide with holes in it.
+      # a run rather than silently producing a guide with holes in it. A key is
+      # missing in a particular language, so the language is part of it.
       def missing_keys
         @missing_keys ||= []
       end
@@ -21,16 +39,39 @@ module Howdoc
         @missing_keys = []
       end
 
+      # Wraps a form field locator so it is named in the language of whichever
+      # edition is being written, rather than in the one the test ran in.
+      def field(locator)
+        Field.new(locator)
+      end
+
       def call(action, locale:, **payload)
-        key = "#{SCOPE}.#{action}"
-        text = I18n.t(key, locale:, default: nil, **escape(payload))
+        sentence = lookup(ACTIONS, action, locale:)
 
-        if text.nil?
-          missing_keys << key unless missing_keys.include?(key)
+        if sentence.nil?
+          record_missing(action_key(action), locale)
           return nil
         end
 
-        text
+        values = resolve(payload, locale)
+        values.empty? ? sentence : I18n.interpolate(sentence, values)
+      end
+
+      # Whether any of the languages a guide is published in has a sentence for
+      # this action. A step no language can say anything about is not recorded
+      # at all -- it would otherwise leave a numbered instruction with nothing
+      # in it, or an illustration of nothing.
+      def known?(action, locales)
+        return false if action.nil?
+
+        return true if locales.any? { |locale| translated?(action, locale) }
+
+        locales.each { |locale| record_missing(action_key(action), locale) }
+        false
+      end
+
+      def translated?(action, locale)
+        !lookup(ACTIONS, action, locale:).nil?
       end
 
       # The label a reader would recognise for a form field.
@@ -41,10 +82,17 @@ module Howdoc
       def field_label(locator, locale:)
         return '' if locator.nil?
 
-        translated = I18n.t("howdoc.fields.#{locator}", locale:, default: nil)
-        return translated if translated
+        lookup(FIELDS, locator, locale:) || Howdoc.config.field_label.call(locator)
+      end
+
+      # A guide's own words -- its title, its introduction -- come from the test
+      # that recorded it and are therefore written in one language. Translating
+      # howdoc.documents.<permalink>.title gives the same guide a heading in
+      # another language without the test knowing there is another language.
+      def document_text(field, key:, locale:, default: nil)
+        return default if key.nil? || key.empty?
 
-        Howdoc.config.field_label.call(locator)
+        lookup(DOCUMENTS, key, field, locale:) || default
       end
 
       # Rails names fields after the model that owns them, which is noise to
@@ -63,10 +111,56 @@ module Howdoc
 
       private
 
-      # Translations carry the markup, values do not. Escaping here means a
-      # label containing an angle bracket cannot break the page it lands on.
-      def escape(payload)
+      # Nothing here asks I18n for a leaf.
+      #
+      # How a key is resolved belongs to the application, and an application
+      # that has switched cascading on answers a missing
+      # "howdoc.documents.some_guide.title" with whatever unrelated top-level
+      # "title" it happens to have. A guide would then be headed with a word
+      # from somewhere else entirely. So the gem's own tree is fetched whole --
+      # it is always there, so nothing cascades past it -- and the leaf is dug
+      # out of the result, where a key that is missing is simply missing.
+      #
+      # An application's fallback chain is still honoured, because a sentence
+      # in the wrong language reads better than a numbered step with nothing
+      # in it.
+      def lookup(*path, locale:)
+        keys = path.map(&:to_sym)
+
+        fallback_chain(locale).each do |candidate|
+          tree = I18n.t(ROOT, locale: candidate, default: nil)
+          next unless tree.is_a?(Hash)
+
+          value = tree.dig(*keys)
+          return value if value.is_a?(String)
+        end
+
+        nil
+      end
+
+      def fallback_chain(locale)
+        return [locale] unless I18n.respond_to?(:fallbacks)
+
+        I18n.fallbacks[locale]
+      rescue StandardError
+        [locale]
+      end
+
+      def action_key(action)
+        "#{ROOT}.#{ACTIONS}.#{action}"
+      end
+
+      def record_missing(key, locale)
+        entry = "#{key} (#{locale})"
+        missing_keys << entry unless missing_keys.include?(entry)
+      end
+
+      # Values that only a language can settle are settled here, and then
+      # escaped like any other: translations carry the markup, values do not, so
+      # a label containing an angle bracket cannot break the page it lands on.
+      def resolve(payload, locale)
         payload.transform_values do |value|
+          value = value.to_howdoc_text(locale) if value.respond_to?(:to_howdoc_text)
           value.is_a?(String) || value.is_a?(Symbol) ? ERB::Util.html_escape(value.to_s) : value
         end
       end

data/lib/howdoc/recorder.rb

@@ -37,16 +37,18 @@ module Howdoc
     end
 
     # Records one instruction. +action+ names an I18n key under howdoc.actions;
-    # the remaining keyword arguments are interpolated into it. Pass
-    # <tt>html:</tt> instead to supply already-rendered markup, for the rare
-    # step no sentence describes.
+    # the remaining keyword arguments are interpolated into it when the guide is
+    # written, once per language. Pass <tt>html:</tt> instead to supply
+    # already-rendered markup, for the rare step no sentence describes.
+    #
+    # Values that read differently in different languages must not be resolved
+    # here: pass Howdoc::Narrator.field(locator) and the label is settled by
+    # each edition as it is written.
     def record(action = nil, html: nil, arrival: false, nodoc: false, **payload)
       return nil if nodoc || !recording?
+      return nil if html.nil? && !Narrator.known?(action, current.locales)
 
-      markup = html || Narrator.call(action, locale: current.locale, **payload)
-      return nil if markup.nil?
-
-      current.new_step(html: markup, arrival:)
+      current.new_step(action:, payload:, html:, arrival:)
     end
 
     # Illustrates the step recorded most recently. Separate from +record+

data/lib/howdoc/step.rb

@@ -1,21 +1,55 @@
 # frozen_string_literal: true
 
 module Howdoc
-  # One numbered instruction in a guide: a sentence, optionally an illustration,
-  # and a flag for the steps that mark the reader's arrival on a new page.
+  # One numbered instruction in a guide: what happened, optionally an
+  # illustration of it, and a flag for the steps that mark the reader's arrival
+  # on a new page.
+  #
+  # What happened is kept as the action and the values it was recorded with,
+  # not as a finished sentence, because the same step is told in every language
+  # the guide is published in.
   class Step
-    attr_reader :number
+    # A step as one language tells it: the sentence composed, the illustration
+    # named as that language's guide refers to it. This is what a template is
+    # handed, so a template never has to know which language it is rendering.
+    Narrated = Struct.new(:number, :html, :screenshot, :arrival, keyword_init: true) do
+      def empty?
+        html.nil? && screenshot.nil?
+      end
+    end
+
+    attr_reader :number, :action, :payload
     attr_accessor :html, :screenshot, :arrival
 
-    def initialize(number:, html: nil, screenshot: nil, arrival: false)
+    def initialize(number:, action: nil, payload: {}, html: nil, screenshot: nil, arrival: false)
       @number = number
+      @action = action
+      @payload = payload
       @html = html
       @screenshot = screenshot
       @arrival = arrival
     end
 
     def empty?
-      html.nil? && screenshot.nil?
+      html.nil? && action.nil? && screenshot.nil?
+    end
+
+    # Markup a caller supplied stands in every language: it was written by the
+    # application, which knew what it was doing.
+    def html_in(locale)
+      return html unless html.nil?
+      return nil if action.nil?
+
+      Narrator.call(action, locale:, **payload)
+    end
+
+    def narrate(edition)
+      Narrated.new(
+        number:,
+        html: html_in(edition.locale),
+        screenshot: (edition.image_filename(number) if screenshot),
+        arrival:
+      )
     end
   end
 end

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/howdoc/writers.rb

@@ -28,16 +28,43 @@ module Howdoc
       Howdoc.config.formats.map { |format| fetch(format).call(document) }
     end
 
-    # Writes the illustrated guide a reader actually opens.
+    # Writes the illustrated guide a reader actually opens -- one page per
+    # language the guide is published in.
     class Html
       def self.call(document)
-        FileUtils.mkdir_p(document.dir)
+        document.editions.map { |edition| write(document, edition) }
+      end
+
+      def self.write(document, edition)
+        FileUtils.mkdir_p(edition.dir)
+        copy_screenshots(document, edition)
+
         markup = Templates.render(
           'document/html/layout.haml',
-          document:, config: Howdoc.config
+          document: edition, config: Howdoc.config
         )
-        File.write(document.path('html'), markup)
-        document.path('html')
+        File.write(edition.path('html'), markup)
+        edition.path('html')
+      end
+
+      # A picture of the application is the same picture whatever language the
+      # page around it is written in, so it is taken once, while the browser is
+      # still on the page, and copied to where each edition looks for it.
+      def self.copy_screenshots(document, edition)
+        return if edition.equal?(document.primary)
+
+        document.steps.each do |step|
+          next if step.screenshot.nil?
+
+          copy_screenshot(File.join(document.image_dir, step.screenshot), edition, step.number)
+        end
+      end
+
+      def self.copy_screenshot(source, edition, number)
+        return unless File.file?(source)
+
+        FileUtils.mkdir_p(edition.image_dir)
+        FileUtils.cp(source, File.join(edition.image_dir, edition.image_filename(number)))
       end
     end
 

data/lib/howdoc.rb

@@ -7,6 +7,7 @@ require_relative 'howdoc/version'
 require_relative 'howdoc/configuration'
 require_relative 'howdoc/narrator'
 require_relative 'howdoc/step'
+require_relative 'howdoc/edition'
 require_relative 'howdoc/document'
 require_relative 'howdoc/screenshot'
 require_relative 'howdoc/recorder'
@@ -58,11 +59,36 @@ module Howdoc
     end
 
     # Begins a guide. Everything recorded until #finish belongs to it.
-    def start(id: nil, title: nil, locale: I18n.locale, permalink: nil, intro: nil)
+    #
+    # A test runs in one language; the guide it records is written in every
+    # language the application publishes, which is config.locales unless this
+    # call names them. Pass +locale:+ for the rare guide that belongs to one
+    # language only -- a page describing something only that language's users
+    # ever see.
+    def start(id: nil, title: nil, locale: nil, locales: nil, permalink: nil, intro: nil)
       return nil unless enabled?
-      return nil if title.to_s.strip.empty?
+      return nil if blank_title?(title)
 
-      Recorder.current = Document.new(id:, title:, locale:, permalink:, intro:)
+      Recorder.current = Document.new(
+        id:, title:, permalink:, intro:,
+        locales: document_locales(locale, locales)
+      )
+    end
+
+    # Which languages a guide is written in: what the caller asked for, else
+    # what the application publishes, else the language the suite is running
+    # in, which is all a single-language application ever needs.
+    def document_locales(locale, locales)
+      chosen = locales || locale || config.locales
+      chosen = I18n.locale if chosen.nil? || Array(chosen).empty?
+
+      Array(chosen).map(&:to_sym)
+    end
+
+    def blank_title?(title)
+      return title.values.all? { |value| blank_title?(value) } if title.is_a?(Hash)
+
+      title.to_s.strip.empty?
     end
 
     # Ends the guide and writes it out. Called even when the test failed, so a

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Priit Tark
@@ -58,6 +58,7 @@ files:
 - lib/howdoc/capybara_actions.rb
 - lib/howdoc/configuration.rb
 - lib/howdoc/document.rb
+- lib/howdoc/edition.rb
 - lib/howdoc/minitest.rb
 - lib/howdoc/narrator.rb
 - lib/howdoc/recorder.rb