multilocale 0.1.0

data/lib/multilocale/locale_file.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "yaml"
+
+module Multilocale
+  # Reads and writes the locale files on disk.
+  #
+  # The path is a template containing `%lang%`, the same convention the npm CLI
+  # uses in multilocale.json:
+  #
+  #   config/locales/%lang%.yml  ->  config/locales/en.yml, config/locales/es.yml, …
+  #
+  # YAML is written the way the i18n gem expects it: a single top-level locale
+  # key, nested below it. Two differences from `npx multilocale download` are
+  # deliberate and both matter to Ruby:
+  #
+  #   * no injected "locale" entry. The CLI writes one into every dictionary it
+  #     generates (only its Swift writer strips it again); in a Rails locale
+  #     file it would surface as the translation `t("locale")`.
+  #   * dotted keys are nested, because i18n resolves them by walking hashes.
+  class LocaleFile
+    FORMATS = %i[yaml json].freeze
+    PLACEHOLDER = "%lang%"
+
+    attr_reader :path_template, :format, :nested, :header, :base_dir
+
+    def initialize(path_template:, format: nil, nested: true, header: nil, base_dir: Dir.pwd)
+      unless path_template.to_s.include?(PLACEHOLDER)
+        raise ConfigurationError, "Path #{path_template.inspect} must contain #{PLACEHOLDER}, e.g. " \
+                                  "config/locales/#{PLACEHOLDER}.yml"
+      end
+
+      @path_template = path_template.to_s
+      @format = (format || self.class.infer_format(@path_template)).to_sym
+
+      unless FORMATS.include?(@format)
+        raise ConfigurationError,
+              "Unsupported format #{@format.inspect} (supported: #{FORMATS.join(', ')}). " \
+              "The npm CLI's cjs/esm/js/swift writers have no equivalent here."
+      end
+
+      @nested = nested
+      @header = header
+      @base_dir = base_dir
+    end
+
+    def self.infer_format(path)
+      case File.extname(path).downcase
+      when ".json" then :json
+      else :yaml
+      end
+    end
+
+    def path_for(language)
+      File.expand_path(path_template.gsub(PLACEHOLDER, language.to_s), base_dir)
+    end
+
+    # Writes one language and returns the absolute path written.
+    def write(dictionary)
+      path = path_for(dictionary.language)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, render(dictionary))
+      path
+    end
+
+    def render(dictionary)
+      body = nested ? dictionary.nested : dictionary.to_h
+
+      case format
+      when :yaml
+        # line_width: -1 keeps long sentences on one line; wrapped YAML is
+        # valid but re-wraps on every unrelated edit and ruins the diff.
+        "#{yaml_header}#{{ dictionary.language.to_s => body }.to_yaml(line_width: -1)}"
+      else
+        # JSON has no comment syntax, so `header` is deliberately dropped here
+        # rather than written as an invalid first line.
+        "#{JSON.pretty_generate(body)}\n"
+      end
+    end
+
+    # Reads one language file back into a Dictionary, flattening the nesting.
+    # Returns nil when the file does not exist.
+    def read(language)
+      path = path_for(language)
+      return nil unless File.exist?(path)
+
+      raw = File.read(path)
+      document =
+        case format
+        when :yaml then YAML.safe_load(raw) || {}
+        else JSON.parse(raw)
+        end
+
+      # A locale file is `{ "en" => { … } }`; anything else is either already
+      # flat or someone else's file, and is taken as it comes.
+      body =
+        if document.is_a?(Hash) && document.size == 1 && document.key?(language.to_s)
+          document[language.to_s]
+        else
+          document
+        end
+
+      Dictionary.new(language.to_s, Dictionary.flatten(body))
+    end
+
+    private
+
+    def yaml_header
+      return "" if header.nil? || header.to_s.empty?
+
+      header.to_s.lines.map { |line| line.start_with?("#") ? line : "# #{line}" }.join.then do |comment|
+        comment.end_with?("\n") ? comment : "#{comment}\n"
+      end
+    end
+  end
+end

data/lib/multilocale/phrase.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # One `{key, value, language}` row. A key translated into 12 locales is 12
+  # phrases, not one phrase with 12 values — every API call and every error
+  # message counts rows, not keys.
+  #
+  # A row can belong to several projects at once (`projects`). Editing it edits
+  # it for all of them, and deleting a key deletes every row it matches
+  # including the shared ones.
+  class Phrase
+    attr_reader :to_h
+
+    def initialize(attributes)
+      @to_h = attributes.is_a?(Phrase) ? attributes.to_h : (attributes || {})
+    end
+
+    def id
+      @to_h["_id"]
+    end
+
+    def key
+      @to_h["key"]
+    end
+
+    def value
+      @to_h["value"]
+    end
+
+    def language
+      @to_h["language"]
+    end
+
+    def projects
+      @to_h["projects"] || []
+    end
+
+    def projects_ids
+      @to_h["projectsIds"] || []
+    end
+
+    def organization_id
+      @to_h["organizationId"]
+    end
+
+    # `googleTranslate` is the pre-2024 spelling and is still the only
+    # provenance flag on older rows, so a reader that only looks at
+    # `machineTranslated` reports human-written text that never was.
+    def machine_translated?
+      value = @to_h.fetch("machineTranslated") { @to_h["googleTranslate"] }
+      !!value
+    end
+
+    # Which engine produced it, when it was machine translated.
+    def model
+      @to_h["model"]
+    end
+
+    def creation_time
+      @to_h["creationTime"]
+    end
+
+    def last_edit_time
+      @to_h["lastEditTime"]
+    end
+
+    def [](key)
+      @to_h[key.to_s]
+    end
+
+    def ==(other)
+      other.is_a?(Phrase) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      "#<Multilocale::Phrase key=#{key.inspect} language=#{language.inspect} value=#{value.inspect}>"
+    end
+
+    ATTRIBUTE_NAMES = {
+      id: "_id",
+      key: "key",
+      value: "value",
+      language: "language",
+      projects: "projects",
+      projects_ids: "projectsIds",
+      machine_translated: "machineTranslated",
+      model: "model"
+    }.freeze
+
+    def self.to_api(attributes)
+      return attributes.to_h if attributes.is_a?(Phrase)
+
+      attributes.each_with_object({}) do |(key, value), document|
+        document[ATTRIBUTE_NAMES[key] || key.to_s] = value
+      end
+    end
+  end
+end

data/lib/multilocale/phrases.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # /api/phrases. Reads need the `phrases:read` scope, writes `phrases:write`.
+  class Phrases
+    # Server-side caps, mirrored here so a bad page size fails locally with a
+    # useful message instead of being silently clamped.
+    MAX_LIMIT = 2001
+    MAX_SKIP = 10_000
+    SORT_FIELDS = %w[_id key language].freeze
+
+    # POST accepts an array, but a few thousand rows in one body is how you
+    # meet a timeout. 200 is comfortably under it.
+    DEFAULT_BATCH_SIZE = 200
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Omitting `limit` returns every matching row — the server treats a missing
+    # limit as unbounded, which is what a full dictionary download wants. Pass
+    # `limit`/`skip` only when you actually want a page.
+    def list(project: nil, language: nil, key: nil, fields: nil, limit: nil, skip: nil, sort_field: nil,
+             sort_direction: nil)
+      if limit && (limit.to_i < 1 || limit.to_i > MAX_LIMIT)
+        raise ArgumentError, "limit must be between 1 and #{MAX_LIMIT} (got #{limit})"
+      end
+
+      if skip && (skip.to_i.negative? || skip.to_i > MAX_SKIP)
+        raise ArgumentError, "skip must be between 0 and #{MAX_SKIP} (got #{skip})"
+      end
+
+      if sort_field && !SORT_FIELDS.include?(sort_field.to_s)
+        raise ArgumentError, "sort_field must be one of #{SORT_FIELDS.join(', ')} (got #{sort_field})"
+      end
+
+      parameters = {
+        "project" => project,
+        "language" => language,
+        "key" => (key && Encoding.phrase_key(key)),
+        "fields" => (fields && Array(fields).join(",")),
+        "limit" => limit,
+        "skip" => skip,
+        "sortField" => sort_field,
+        "sortDirection" => sort_direction
+      }
+
+      Array(@client.get("phrases", params: parameters)).map { |attributes| Phrase.new(attributes) }
+    end
+
+    # Every row of one key, one per language.
+    def find_by_key(key, project: nil)
+      list(key: key, project: project)
+    end
+
+    # Creates or overwrites rows. A row with an `_id` that already exists is
+    # replaced wholesale (it is an upsert, not a patch): send the whole row.
+    #
+    #   phrases.upsert(key: "cart.title", value: "Cart", language: "en", projects: ["website"])
+    #
+    # `projects` must name the key's project, otherwise the row is created but
+    # no download will ever include it.
+    def upsert(phrases = nil, batch_size: DEFAULT_BATCH_SIZE, **attributes)
+      rows =
+        if phrases.nil?
+          attributes.empty? ? [] : [attributes]
+        else
+          phrases.is_a?(Array) ? phrases : [phrases]
+        end
+      return [] if rows.empty?
+
+      rows.each_slice(batch_size).flat_map do |batch|
+        payload = batch.map { |row| Phrase.to_api(row) }
+        # The API answers with a bare object for a single-element body and an
+        # array otherwise, so both shapes have to be handled.
+        result = @client.post("phrases", body: payload.size == 1 ? payload.first : payload)
+        (result.is_a?(Array) ? result : [result]).map { |attributes| Phrase.new(attributes) }
+      end
+    end
+
+    def update(id, attributes)
+      Phrase.new(@client.put("phrases/#{Encoding.percent_encode(id)}", body: Phrase.to_api(attributes)))
+    end
+
+    # Deletes EVERY language of `key` in `project` — a 30-locale key is 30 rows
+    # gone in one call. Rows shared with other projects are deleted too, not
+    # detached from this one. Returns the deleted rows.
+    def delete(key:, project:)
+      raise ArgumentError, "key is required" if key.nil? || key.to_s.empty?
+      raise ArgumentError, "project is required" if project.nil? || project.to_s.empty?
+
+      result = @client.delete("phrases", params: { "key" => Encoding.phrase_key(key), "project" => project })
+      Array(result).map { |attributes| Phrase.new(attributes) }
+    end
+  end
+end

data/lib/multilocale/project.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # A project: the unit an API key is scoped to, and the thing that owns the
+  # locale list every download is written from.
+  #
+  # The wire format is the API's camelCase document; the readers are the Ruby
+  # names. `#to_h` always returns the untouched document, so a round-trip
+  # through this class never drops a field the API added yesterday.
+  class Project
+    attr_reader :to_h
+
+    def initialize(attributes)
+      @to_h = attributes.is_a?(Project) ? attributes.to_h : (attributes || {})
+    end
+
+    def id
+      @to_h["_id"]
+    end
+
+    def name
+      @to_h["name"]
+    end
+
+    def organization_id
+      @to_h["organizationId"]
+    end
+
+    def default_locale
+      @to_h["defaultLocale"]
+    end
+
+    # The complete locale list. Updating it REPLACES it: a project update that
+    # omits a locale removes it, it does not merge.
+    def locales
+      @to_h["locales"] || []
+    end
+
+    # Free-text translation context, prepended to every machine translation.
+    def context
+      @to_h["context"]
+    end
+
+    # Server-side download paths. The npm CLI resolves `project.paths ||
+    # config.paths`, so a value set here wins over the local multilocale.json.
+    def paths
+      @to_h["paths"]
+    end
+
+    def creation_time
+      @to_h["creationTime"]
+    end
+
+    def last_edit_time
+      @to_h["lastEditTime"]
+    end
+
+    def [](key)
+      @to_h[key.to_s]
+    end
+
+    def ==(other)
+      other.is_a?(Project) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      "#<Multilocale::Project id=#{id.inspect} name=#{name.inspect} locales=#{locales.size}>"
+    end
+
+    ATTRIBUTE_NAMES = {
+      id: "_id",
+      name: "name",
+      default_locale: "defaultLocale",
+      locales: "locales",
+      context: "context",
+      paths: "paths"
+    }.freeze
+
+    # Snake_case keyword arguments -> the camelCase document the API stores.
+    # String keys are passed through untouched so anything not modelled here
+    # can still be sent.
+    def self.to_api(attributes)
+      return attributes.to_h if attributes.is_a?(Project)
+
+      attributes.each_with_object({}) do |(key, value), document|
+        document[ATTRIBUTE_NAMES[key] || key.to_s] = value
+      end
+    end
+  end
+end

data/lib/multilocale/projects.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # /api/projects. Reads need the `projects:read` scope, writes `projects:write`.
+  class Projects
+    def initialize(client)
+      @client = client
+    end
+
+    # Every project the credential can see. A project-scoped API key sees
+    # exactly one — the server filters the list, it does not 403.
+    def list
+      Array(@client.get("projects")).map { |attributes| Project.new(attributes) }
+    end
+
+    # Accepts an id (24 hex characters) or a name. Names are unique per
+    # organization, not globally, and the credential supplies the organization.
+    def find(id_or_name)
+      raise ConfigurationError, "Project id or name required" if id_or_name.nil? || id_or_name.to_s.empty?
+
+      Project.new(@client.get("projects/#{Encoding.percent_encode(id_or_name)}"))
+    end
+
+    # Returns nil instead of raising when there is no such project.
+    def find_by(id_or_name)
+      find(id_or_name)
+    rescue NotFoundError
+      nil
+    end
+
+    # create(name: "website", default_locale: "en", locales: %w[en es fr])
+    def create(attributes)
+      Project.new(@client.post("projects", body: Project.to_api(attributes)))
+    end
+
+    # `locales:` is a REPLACEMENT, not a merge. Read the project first and send
+    # the full list, or you will silently drop the locales you left out.
+    def update(id, attributes)
+      Project.new(@client.put("projects/#{Encoding.percent_encode(id)}", body: Project.to_api(attributes)))
+    end
+  end
+end

data/lib/multilocale/sync.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # Moves phrases between multilocale.com and the locale files in a repository.
+  #
+  #   sync = Multilocale::Sync.new(client: client, config: Multilocale::ConfigFile.discover)
+  #   sync.pull   # API   -> config/locales/*.yml
+  #   sync.push   # files -> API
+  #
+  # Pull is the one to wire into a rake task or CI job; push exists so a
+  # developer who edited a locale file by hand can send it back rather than
+  # retyping it in the dashboard.
+  class Sync
+    # What a pull did, so a CLI or a rake task can report it without guessing.
+    Result = Struct.new(:project, :files, :languages, :phrases, :empty_locales, keyword_init: true)
+
+    attr_reader :client, :config, :base_dir
+
+    def initialize(client:, config: nil, project: nil, paths: nil, nested: nil, header: nil, base_dir: nil)
+      @client = client
+      @config = config
+      @project = project
+      @paths = paths
+      @nested = nested
+      @header = header
+      @base_dir = base_dir || config&.directory || Dir.pwd
+    end
+
+    def project
+      @project || config&.project || client.project ||
+        raise(ConfigurationError, <<~MESSAGE)
+          No project. Pass project: to Sync.new, set "projectId" in #{ConfigFile::FILENAME},
+          or export MULTILOCALE_PROJECT.
+        MESSAGE
+    end
+
+    def paths
+      value = @paths || config&.paths
+      value = Array(value)
+      return value unless value.empty?
+
+      raise ConfigurationError, <<~MESSAGE
+        No output paths. Pass paths: to Sync.new or add them to #{ConfigFile::FILENAME}:
+
+          { "paths": ["config/locales/#{LocaleFile::PLACEHOLDER}.yml"] }
+      MESSAGE
+    end
+
+    # Downloads every phrase of the project and rewrites the locale files.
+    #
+    # Locales the project declares but has no phrases for are reported in
+    # `Result#empty_locales` and left alone: writing an empty file for them
+    # would make i18n treat a missing translation as an empty string.
+    def pull(languages: nil)
+      # Local configuration is validated before the first request: a missing
+      # path template should not cost a round trip to find out about.
+      writers
+
+      resolved = resolve_project
+      rows = client.phrases.list(project: resolved.name)
+      dictionaries = Dictionary.from_phrases(rows)
+
+      wanted = languages || config&.locales || resolved.locales
+      wanted = dictionaries.keys if wanted.nil? || wanted.empty?
+
+      files = []
+      empty = []
+
+      wanted.sort.each do |language|
+        dictionary = dictionaries[language]
+
+        if dictionary.nil? || dictionary.empty?
+          empty << language
+          next
+        end
+
+        writers.each { |writer| files << writer.write(dictionary) }
+      end
+
+      Result.new(
+        project: resolved,
+        files: files,
+        languages: wanted.sort - empty,
+        phrases: rows.size,
+        empty_locales: empty
+      )
+    end
+
+    # Reads the locale files back and upserts them as phrase rows.
+    #
+    # Every row is sent with `projects: [name]`; a row created without it exists
+    # in the organization but belongs to no project, and no download will ever
+    # include it again.
+    def push(languages: nil)
+      resolved = resolve_project
+      writer = writers.first
+      wanted = languages || config&.locales || resolved.locales
+
+      rows = wanted.flat_map do |language|
+        dictionary = writer.read(language)
+        next [] if dictionary.nil?
+
+        dictionary.map do |key, value|
+          { key: key, value: value, language: language, projects: [resolved.name] }
+        end
+      end
+
+      client.phrases.upsert(rows)
+    end
+
+    def resolve_project
+      client.projects.find(project)
+    rescue NotFoundError
+      raise NotFoundError.new(
+        "No project #{project.inspect} in this organization. `multilocale-ruby projects` lists the ones " \
+        "this credential can see.",
+        status: 404
+      )
+    end
+
+    private
+
+    def writers
+      @writers ||= paths.map do |path|
+        LocaleFile.new(
+          path_template: path,
+          format: config&.format,
+          nested: @nested.nil? ? (config.nil? || config.nested?) : @nested,
+          header: @header || config&.header,
+          base_dir: base_dir
+        )
+      end
+    end
+  end
+end

data/lib/multilocale/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Multilocale
+  VERSION = "0.1.0"
+end

data/lib/multilocale.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "multilocale/version"
+require_relative "multilocale/errors"
+require_relative "multilocale/encoding"
+require_relative "multilocale/project"
+require_relative "multilocale/phrase"
+require_relative "multilocale/dictionary"
+require_relative "multilocale/locale_file"
+require_relative "multilocale/config_file"
+require_relative "multilocale/projects"
+require_relative "multilocale/phrases"
+require_relative "multilocale/client"
+require_relative "multilocale/sync"
+
+# Ruby client for the Multilocale translation API (https://www.multilocale.com).
+#
+#   client = Multilocale.client                       # reads MULTILOCALE_API_KEY
+#   client.dictionary(project: "website", language: "es").to_h
+#   #=> { "cart.title" => "Carrito", … }
+#
+# The gem talks to the REST API and writes i18n-shaped locale files; the i18n
+# gem renders them. It deliberately does not wrap I18n itself — a translation
+# backend that makes a network call per lookup is how a marketing page ends up
+# depending on someone else's uptime.
+module Multilocale
+  class << self
+    # Builds a client from the environment, or from explicit keywords.
+    def client(**options)
+      Client.new(**options)
+    end
+
+    # Convenience for the common one-liner: one language of one project.
+    def dictionary(project:, language:, **options)
+      client(**options).dictionary(project: project, language: language)
+    end
+  end
+end