multilocale 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75db6f0b36c95b3bbcb2c43a76c1764d40bb1cb4d4cb329b7f1ef541915588cb
+  data.tar.gz: 17c4ba2fd230cc8078a2ecc47a941ff59c01a89868ca9e2ff8cc96bb3ef0088d
+SHA512:
+  metadata.gz: b55ec4bcc946785519ff30b691531acfe4a39179918f6fd89050ef1126c9ea09bcb8f81ff017fc943a45f358df7199ef77cf7c0a44c9777431e14df02a3548a0
+  data.tar.gz: 77ac28ae81c76322f0b97caee8be408f7f8554acd248017cf32c0c12b78256745110f5b8df5c43911887dd1479af8e4432a6579472c7136fb66f51afb886273b

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this gem are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version is
+the one in `lib/multilocale/version.rb`.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-04
+
+First release of the rewritten gem. The repository previously held nothing but
+a licence file; nothing published under this name before.
+
+### Added
+
+- `Multilocale::Client` for the REST API: `Authorization: Basic base64(secret)`,
+  timeouts, exponential-backoff retries on 429 and 5xx, and errors mapped onto
+  `AuthenticationError` / `PermissionError` / `NotFoundError` /
+  `RateLimitedError` / `ServerError` / `ConnectionError`.
+- `client.projects` — list, find by id or name, create, update.
+- `client.phrases` — list with filters and paging, upsert (batched), update,
+  delete, plus `client.dictionary` / `client.dictionaries`.
+- `Multilocale::LocaleFile` — reads and writes i18n-shaped
+  `config/locales/*.yml` (and JSON), nesting dotted keys on the way out and
+  flattening them on the way back.
+- `Multilocale::Sync` — `pull` and `push`, driven by `multilocale.json`.
+- `multilocale-ruby` command: `pull`, `push`, `projects`, `phrases`, `version`,
+  with `--json` output. Credentials come from the environment only.
+- `example/` — a four-language Sinatra application with its translations
+  committed, so a clone runs offline.
+
+[unreleased]: https://github.com/multilocale/multilocale-ruby-gem/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/multilocale/multilocale-ruby-gem/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Multilocale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# multilocale (Ruby)
+
+Ruby client for [Multilocale](https://www.multilocale.com), the translation
+management platform. It reads and writes projects and phrases over the REST
+API, and syncs them into the locale files the [i18n
+gem](https://github.com/ruby-i18n/i18n) — and therefore Rails — already load.
+
+```ruby
+client = Multilocale.client                                   # MULTILOCALE_API_KEY
+client.dictionary(project: "website", language: "es").to_h
+#=> { "cart.title" => "Carrito", "nav.language" => "Idioma", … }
+```
+
+```console
+$ multilocale-ruby pull
+website: 412 phrases in 6 languages
+  wrote config/locales/en.yml
+  wrote config/locales/es.yml
+  …
+```
+
+- No runtime dependencies: `net/http`, `json` and `yaml` from the standard library.
+- No network call while a page is being served. Translations are downloaded at
+  build time and committed, so the site renders offline and stays up when
+  multilocale.com does not.
+- Ruby >= 3.2.
+
+## Install
+
+```ruby
+# Gemfile
+gem "multilocale", "~> 0.1"
+```
+
+```console
+gem install multilocale
+```
+
+> **0.1.0 is not on RubyGems yet.** Until it is, install from a checkout —
+> `gem "multilocale", path: "…"` in your Gemfile, or `rake build && gem install
+> pkg/multilocale-0.1.0.gem`. `example/` in this repository already resolves the
+> gem from `path: ".."`, so it needs nothing extra.
+
+## The workflow this gem is for
+
+1. **Phrases live in a project on multilocale.com.** A project has a name, a
+   default locale and a complete locale list. A phrase is one
+   `{key, value, language}` row, so a key translated into 12 locales is 12 rows.
+2. **`multilocale-ruby pull` writes them to disk** as
+   `config/locales/<locale>.yml`, nested the way i18n expects.
+3. **You commit the result.** The files are part of the application, reviewed
+   in the same pull request as the code that renders them.
+4. **The i18n gem renders them.** Nothing in the request path talks to
+   Multilocale.
+
+Editing a locale file by hand and sending it back up is `multilocale-ruby push
+--yes`.
+
+## Authenticate
+
+Create a key at [app.multilocale.com](https://app.multilocale.com) → **API
+keys**, and export the secret:
+
+```console
+export MULTILOCALE_API_KEY=…
+```
+
+The API expects `Authorization: Basic base64(secret)` — the secret alone,
+base64'd, **with no colon and no key/secret pair**. This gem does that for you;
+it is worth knowing because a hand-rolled `curl` with `-u key:secret` is the
+single most common first failure.
+
+The secret selects the organization *and* the project, so there is no tenant
+parameter to pass, and a key scoped to one project cannot read another's
+phrases even if you ask for it.
+
+Scopes are `projects:read`, `projects:write`, `phrases:read`, `phrases:write`.
+New keys get the read scopes only; `pull` needs `projects:read` +
+`phrases:read`, `push` also needs `phrases:write`.
+
+There is deliberately **no `--api-key` flag**. A secret on the command line is
+readable in the process table and lives in your shell history forever.
+
+## Configure
+
+`multilocale.json` in the repository root, the same file the
+[npm CLI](https://www.npmjs.com/package/multilocale) reads:
+
+```json
+{
+  "projectId": "website",
+  "defaultLocale": "en",
+  "locales": ["en", "es", "fr", "it"],
+  "paths": ["config/locales/%lang%.yml"]
+}
+```
+
+- `projectId` accepts an id **or** a name. Names are unique per organization,
+  which is what makes this portable between accounts.
+- `paths` are resolved relative to `multilocale.json`, so `rake` from a
+  subdirectory writes the same files as `rake` from the root.
+- `%lang%` is replaced with each locale.
+
+Every command works with no flags once this file exists. Nothing ever prompts —
+an interactive picker in a CI job is a hung build.
+
+## Command line
+
+```console
+multilocale-ruby pull                       # API   -> config/locales/*.yml
+multilocale-ruby push --yes                 # files -> API (overwrites remote values)
+multilocale-ruby projects                   # what this credential can see
+multilocale-ruby phrases --language es      # one dictionary, key = value
+multilocale-ruby pull --json                # machine-readable report
+```
+
+The executable is `multilocale-ruby`, not `multilocale`: that name belongs to
+the npm CLI, and two tools fighting over one name on `PATH` helps nobody.
+
+## In a Rails application
+
+```ruby
+# lib/tasks/multilocale.rake
+require "multilocale"
+
+namespace :multilocale do
+  desc "Download the project's phrases into config/locales"
+  task :pull do
+    result = Multilocale::Sync.new(
+      client: Multilocale.client,
+      config: Multilocale::ConfigFile.discover(Rails.root)
+    ).pull
+
+    puts "#{result.phrases} phrases in #{result.languages.size} languages"
+  end
+end
+```
+
+`config/locales/*.yml` is already on `I18n.load_path`, so `t("cart.title")`
+works with no further wiring. `example/` in this repository is the same thing in
+Sinatra, small enough to read in one sitting.
+
+## Library
+
+```ruby
+client = Multilocale::Client.new(api_key: ENV["MULTILOCALE_API_KEY"])
+
+client.projects.list                                  # => [Multilocale::Project]
+client.projects.find("website")                       # by id or by name
+client.projects.create(name: "docs", default_locale: "en", locales: %w[en fr])
+client.projects.update(id, locales: %w[en fr de])     # replaces the locale list
+
+client.phrases.list(project: "website", language: "es")
+client.phrases.list(project: "website", key: "cart.title")
+client.phrases.upsert(key: "cart.title", value: "Cart", language: "en", projects: ["website"])
+client.phrases.update(phrase_id, value: "Basket")
+client.phrases.delete(key: "cart.title", project: "website")
+
+client.dictionary(project: "website", language: "es")  # => Multilocale::Dictionary
+client.dictionaries(project: "website")                # => { "en" => …, "es" => … }
+```
+
+Every call raises a `Multilocale::Error` subclass on failure —
+`AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404),
+`RateLimitedError` (429), `ServerError` (5xx), `ConnectionError`. 429 and 5xx
+are retried with exponential backoff; 4xx is not, because retrying a missing
+scope only burns rate limit.
+
+### Things worth knowing before you write
+
+- **`locales:` on a project update is a replacement, not a merge.** Read the
+  project, add to `project.locales`, send the whole list back. Omitting a
+  locale removes it.
+- **`delete` removes every language of a key**, not one row — and rows shared
+  with other projects are deleted, not detached from this one.
+- **`upsert` overwrites.** It is not a patch: send the whole row.
+- **A phrase needs `projects: [name]`.** Without it the row exists in the
+  organization but belongs to no project, and no download will include it.
+- **`list` without `limit` returns everything.** Pass `limit`/`skip` only when
+  you want a page; they cap at 2001 and 10000.
+
+## Locale files
+
+`config/locales/es.yml`, as written by `pull`:
+
+```yaml
+# Generated by `multilocale-ruby pull`. Edit the phrases on multilocale.com, not here.
+---
+es:
+  cart:
+    title: Carrito
+  greeting: "¡Hola, %{name}!"
+```
+
+Two details that matter to Ruby specifically:
+
+- **Dotted keys are nested.** i18n resolves `t("cart.title")` by walking
+  hashes, so a flat `"cart.title":` key would never be found. `push` flattens
+  them again on the way back.
+- **No `locale:` entry is injected.** The npm CLI writes one into every
+  dictionary it generates; in a Rails locale file it would show up as the
+  translation `t("locale")`.
+
+`%{name}` and `%{count}` survive machine translation: Multilocale checks that
+every `{…}` placeholder in the source is still present in the translation and
+repairs it if not.
+
+Pluralisation is ordinary i18n — store `items.one` and `items.other` as two
+keys and call `t("items", count: 3)`.
+
+## Example application
+
+```console
+cd example
+bundle install
+bundle exec ruby app.rb        # http://localhost:4567
+```
+
+Four locales, translations committed, no credentials needed. `/en/`, `/es/`,
+`/fr/`, `/it/`. It resolves the gem from `path: ".."`, so it runs against the
+code in this checkout and works before the gem is on RubyGems.
+
+## Documentation
+
+- REST API and CLI guides: <https://www.multilocale.com/developers/>
+- Issues: <https://github.com/multilocale/multilocale-ruby-gem/issues>
+
+## License
+
+MIT.

data/exe/multilocale-ruby

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "multilocale/cli"
+
+exit Multilocale::CLI.new.run(ARGV)

data/lib/multilocale/cli.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "../multilocale"
+
+module Multilocale
+  # `multilocale-ruby` — the thin command wrapper around this gem.
+  #
+  # The name is not `multilocale` on purpose: that binary belongs to the npm
+  # CLI (`npm i -g multilocale`), and two tools fighting over one name on PATH
+  # is a support ticket nobody enjoys.
+  #
+  # Credentials come from the environment only. A secret passed as
+  # `--api-key=…` is in the process table for every user on the machine and in
+  # ~/.zsh_history forever, so there is no such flag.
+  class CLI
+    BANNER = <<~USAGE
+      multilocale-ruby #{VERSION}
+
+      Usage:
+        multilocale-ruby pull [options]        download phrases into locale files
+        multilocale-ruby push [options]        upload locale files as phrases
+        multilocale-ruby projects [options]    list the projects this credential can see
+        multilocale-ruby phrases [options]     print one language as key = value
+        multilocale-ruby version
+
+      Options:
+        -p, --project NAME     project id or name (default: multilocale.json)
+        -c, --config PATH      path to multilocale.json (default: nearest one)
+            --path TEMPLATE    output path containing %lang% (repeatable)
+        -l, --language LANG    restrict to one language (repeatable)
+            --flat             write flat "a.b" keys instead of nested hashes
+            --json             machine-readable output
+            --yes              required by push, which overwrites remote rows
+        -h, --help
+
+      Environment:
+        MULTILOCALE_API_KEY        API key secret (app.multilocale.com -> API keys)
+        MULTILOCALE_ACCESS_TOKEN   operator session token, as an alternative
+        MULTILOCALE_API_URL        override the API host
+        MULTILOCALE_PROJECT        default project id or name
+    USAGE
+
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # Returns a process exit status: 0 ok, 1 failure, 2 usage.
+    def run(argv)
+      command = argv.first
+
+      return usage(0) if command.nil? || %w[-h --help help].include?(command)
+      return version if %w[version --version -v].include?(command)
+
+      options = parse(argv[1..] || [])
+
+      case command
+      when "pull" then pull(options)
+      when "push" then push(options)
+      when "projects" then projects(options)
+      when "phrases" then phrases(options)
+      else
+        @stderr.puts("Unknown command: #{command}")
+        usage(2)
+      end
+    rescue ConfigurationError, ApiError, ConnectionError, Error, ArgumentError => error
+      @stderr.puts(error.message)
+      1
+    end
+
+    private
+
+    def parse(argv)
+      options = { paths: [], languages: [] }
+
+      parser = OptionParser.new do |parser|
+        parser.banner = BANNER
+        parser.on("-p", "--project NAME") { |value| options[:project] = value }
+        parser.on("-c", "--config PATH") { |value| options[:config] = value }
+        parser.on("--path TEMPLATE") { |value| options[:paths] << value }
+        parser.on("-l", "--language LANG") { |value| options[:languages] << value }
+        parser.on("--flat") { options[:flat] = true }
+        parser.on("--json") { options[:json] = true }
+        parser.on("--yes") { options[:yes] = true }
+        parser.on("-h", "--help") { options[:help] = true }
+      end
+
+      parser.parse(argv)
+      options
+    end
+
+    def usage(status)
+      (status.zero? ? @stdout : @stderr).puts(BANNER)
+      status
+    end
+
+    def version
+      @stdout.puts("multilocale-ruby #{VERSION}")
+      0
+    end
+
+    def client(options)
+      # Passing `project: nil` would override the client's own MULTILOCALE_PROJECT
+      # default with nil, so the keyword is only supplied when there is one.
+      options[:project] ? Client.new(project: options[:project]) : Client.new
+    end
+
+    def config(options)
+      return ConfigFile.load(options[:config]) if options[:config]
+
+      ConfigFile.discover
+    end
+
+    def sync(options)
+      Sync.new(
+        client: client(options),
+        config: config(options),
+        project: options[:project],
+        paths: (options[:paths].empty? ? nil : options[:paths]),
+        nested: (options[:flat] ? false : nil)
+      )
+    end
+
+    def pull(options)
+      return usage(0) if options[:help]
+
+      result = sync(options).pull(languages: languages(options))
+
+      if options[:json]
+        @stdout.puts(JSON.pretty_generate(
+                       ok: true,
+                       project: result.project.name,
+                       phrases: result.phrases,
+                       languages: result.languages,
+                       empty_locales: result.empty_locales,
+                       files: result.files
+                     ))
+      else
+        @stdout.puts("#{result.project.name}: #{result.phrases} phrases in #{result.languages.size} languages")
+        result.files.each { |file| @stdout.puts("  wrote #{relative(file)}") }
+        unless result.empty_locales.empty?
+          @stdout.puts("  no phrases yet for: #{result.empty_locales.join(', ')} (files left untouched)")
+        end
+      end
+
+      0
+    end
+
+    def push(options)
+      return usage(0) if options[:help]
+
+      unless options[:yes]
+        @stderr.puts("push overwrites the remote value of every key in the files it reads. Re-run with --yes.")
+        return 2
+      end
+
+      rows = sync(options).push(languages: languages(options))
+
+      if options[:json]
+        @stdout.puts(JSON.pretty_generate(ok: true, phrases: rows.size))
+      else
+        @stdout.puts("pushed #{rows.size} phrases")
+      end
+
+      0
+    end
+
+    def projects(options)
+      return usage(0) if options[:help]
+
+      list = client(options).projects.list
+
+      if options[:json]
+        @stdout.puts(JSON.pretty_generate(list.map(&:to_h)))
+      else
+        list.sort_by { |project| project.name.to_s }.each do |project|
+          @stdout.puts("#{project.name}  #{project.id}  #{project.locales.size} locales")
+        end
+      end
+
+      0
+    end
+
+    def phrases(options)
+      return usage(0) if options[:help]
+
+      language = languages(options)&.first
+      raise ArgumentError, "phrases needs --language" if language.nil?
+
+      dictionary = client(options).dictionary(
+        project: options[:project] || config(options)&.project,
+        language: language
+      )
+
+      if options[:json]
+        @stdout.puts(JSON.pretty_generate(dictionary.to_h))
+      else
+        dictionary.each { |key, value| @stdout.puts("#{key} = #{value}") }
+      end
+
+      0
+    end
+
+    def languages(options)
+      options[:languages].empty? ? nil : options[:languages]
+    end
+
+    def relative(path)
+      path.sub("#{Dir.pwd}/", "")
+    end
+  end
+end