web_translate_it 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01e00c6188bc51a7520d8a712f988f14125e606fd27a8cd7a8d1576075a433d
-  data.tar.gz: 5c1e552315ce4837b6505f2af0e1f911f4a625bdfcc3011f432502766e8c21b3
+  metadata.gz: 5e4d18f41ea8a29e79e6d789db02d52b1eb92d88504050755a7564872f3b5e59
+  data.tar.gz: d615308a0f20887d376b2f2b1556d066463334fe436da6b7aa893704b1b899e8
 SHA512:
-  metadata.gz: 6a13defd7a2f234d187d496a4da810b56abd06a98a07458e9110ca81be81aa93388c5d65f7804a5ed7fcacea0d2ddc617d2bc1be66c6baf57d98fa545710bf4f
-  data.tar.gz: 888436899b2d2f0e00c734f9bbb20a1692f9b4a3d1aa1cb10ce100215bc3b5d362d19176f2c5855baa70ce312adf5ee5415c489a6ee71ba4ebb0a292266120d4
+  metadata.gz: 8fa287ad61eb72fcb01c39e006bbdaaf864cdd55f76c814781077fc0f8ca1a77c93df066f7e66a07ee7d93f4c1496d0b421eaa458c2dcdbd1e0331550078dbb5
+  data.tar.gz: fe40d7dea985eff437449bae98799574b50c2757bbb77480d50cfe261bf06ba0d1f61b306a420c0efb3d56253fca3f2117d4a8700b7a0154ddf52f9294df70cb

data/history.md

@@ -1,3 +1,10 @@
+## Version 3.5.0 / 2026-11-05
+
+* Support the new API tokens (project, personal, integration) besides the project API keys. The environment variable `WTI_PROJECT_API_KEY` and the `api_key` setting in `.wti` keep their names.
+* Support organization tokens: set `project_id` in `.wti`, or `WTI_PROJECT_ID`, to the project's numeric id and `wti` addresses `/api/projects/<id>` instead of `/api/projects/current`. A non-numeric id is rejected. When the API finds no project for a `wti_` token at `/api/projects/current`, `wti` prints a hint, once. `wti init` writes `project_id` into `.wti` when `WTI_PROJECT_ID` is set.
+* Friendlier errors: a project accepting API tokens only (`legacy_token_disabled`), a revoked or expired token (`invalid_token`) and a read-only token used for writing (`insufficient_scope`) now say what to do.
+* User-facing text says "API token" rather than "Project API Key".
+
 ## Version 3.4.0 / 2026-11-04
 
 * **The project API key is now sent in an `Authorization: Bearer` header instead of in the URL.** Requests go to `/api/projects/current/...` rather than `/api/projects/<api key>/...`, so the key no longer ends up in proxy, load balancer and server logs. webtranslateit.com accepts the header since 2026-11-04. Earlier `wti` versions keep working: the API still accepts the key in the URL.

data/lib/web_translate_it/api_resource.rb

@@ -19,7 +19,7 @@ module WebTranslateIt
 
     def self.find_all(connection, params = {}) # rubocop:todo Metrics/AbcSize, Metrics/MethodLength
       params = params.transform_keys(&:to_s)
-      url = "#{Connection::PROJECT_PATH}/#{resource_path}"
+      url = "#{Connection.project_path}/#{resource_path}"
       url += "?#{HashUtil.to_params(filter_params(params))}" unless params.empty?
 
       Concurrency.with_retries do
@@ -43,7 +43,7 @@ module WebTranslateIt
 
     def self.find(connection, id)
       Concurrency.with_retries do
-        response = connection.get("#{Connection::PROJECT_PATH}/#{resource_path}/#{id}")
+        response = connection.get("#{Connection.project_path}/#{resource_path}/#{id}")
         return nil if response.code.to_i == 404
 
         record = new(JSON.parse(response.body), connection: connection)
@@ -66,7 +66,7 @@ module WebTranslateIt
 
     def delete
       Concurrency.with_retries do
-        HttpResponse.handle_response(connection.delete("#{Connection::PROJECT_PATH}/#{self.class.resource_path}/#{id}"))
+        HttpResponse.handle_response(connection.delete("#{Connection.project_path}/#{self.class.resource_path}/#{id}"))
       end
     end
 
@@ -76,7 +76,7 @@ module WebTranslateIt
       return nil if new_record
 
       Concurrency.with_retries do
-        response = HttpResponse.handle_response(connection.get("#{Connection::PROJECT_PATH}/#{self.class.resource_path}/#{id}/locales/#{locale}/translations"))
+        response = HttpResponse.handle_response(connection.get("#{Connection.project_path}/#{self.class.resource_path}/#{id}/locales/#{locale}/translations"))
         json = JSON.parse(response)
         return nil if json.empty?
 
@@ -106,13 +106,13 @@ module WebTranslateIt
       end
 
       Concurrency.with_retries do
-        HttpResponse.handle_response(connection.put("#{Connection::PROJECT_PATH}/#{self.class.resource_path}/#{id}", body: to_json))
+        HttpResponse.handle_response(connection.put("#{Connection.project_path}/#{self.class.resource_path}/#{id}", body: to_json))
       end
     end
 
     def create
       Concurrency.with_retries do
-        raw = connection.post("#{Connection::PROJECT_PATH}/#{self.class.resource_path}", body: to_json(with_translations: true))
+        raw = connection.post("#{Connection.project_path}/#{self.class.resource_path}", body: to_json(with_translations: true))
         response = JSON.parse(HttpResponse.handle_response(raw))
         self.id = response['id']
         self.new_record = false

data/lib/web_translate_it/commands/init.rb

@@ -4,12 +4,14 @@ module WebTranslateIt
 
   module Commands
 
-    class Init < Base
+    class Init < Base # rubocop:todo Metrics/ClassLength
 
       ENV_API_KEY = 'WTI_PROJECT_API_KEY'
 
       def call
         puts '# Initializing project'
+        Connection.hint_without_config_file = true
+        validate_project_id
         api_key, path = read_parameters
         ensure_directory_exists(path)
         project_info = JSON.parse(WebTranslateIt::Project.fetch_info(api_key))['project']
@@ -21,15 +23,21 @@ module WebTranslateIt
 
       private
 
+      def validate_project_id
+        Connection.project_id
+      rescue ArgumentError => e
+        abort StringUtil.failure(e.message)
+      end
+
       def read_parameters
         if parameters.any?
           warn_env_takes_precedence if env_api_key && parameters[0] != env_api_key
           [parameters[0], '.wti']
         elsif env_api_key
-          puts " Using the Project API Key from #{ENV_API_KEY}."
+          puts " Using the API token from #{ENV_API_KEY}."
           [env_api_key, Prompt.ask(' Path to configuration file:', '.wti')]
         else
-          [Prompt.ask(' Project API Key:'), Prompt.ask(' Path to configuration file:', '.wti')]
+          [Prompt.ask(' API token:'), Prompt.ask(' Path to configuration file:', '.wti')]
         end
       end
 
@@ -54,7 +62,7 @@ module WebTranslateIt
         return if git?('check-ignore', '-q', path)
 
         puts ''
-        puts StringUtil.important(" Warning: `#{path}` contains your Project API Key and is not ignored by git.")
+        puts StringUtil.important(" Warning: `#{path}` contains your API token and is not ignored by git.")
         puts "    Add `#{path}` to .gitignore, or keep the key out of the file: set #{ENV_API_KEY}"
         puts "    and use `api_key: <%= ENV['#{ENV_API_KEY}'] %>` in `#{path}`."
       end
@@ -112,14 +120,22 @@ module WebTranslateIt
         key_from_env?(api_key) ? "<%= ENV['#{ENV_API_KEY}'] %>" : api_key
       end
 
+      # Organization tokens reach a project by its numeric id only. Written when
+      # WTI_PROJECT_ID is set, so the generated file is unchanged otherwise.
+      def project_id_block
+        return '' if ENV.fetch('WTI_PROJECT_ID', '').strip.empty?
+
+        "\n# Project id, required for organization tokens. WTI_PROJECT_ID takes precedence over this value.\nproject_id: #{Connection.project_id}\n"
+      end
+
       def generate_configuration(api_key, project_info)
         <<~FILE
-          # Required - The Project API Token from WebTranslateIt.com
+          # Required - The API token from WebTranslateIt.com (project, personal, integration or organization token)
           # More information: https://github.com/webtranslateit/webtranslateit/wiki#configuration-file
           # The #{ENV_API_KEY} environment variable, when set, takes precedence over this value.
 
           api_key: #{api_key_line(api_key)}
-
+          #{project_id_block}
           # Optional - Locales not to sync with WebTranslateIt.
           # Takes a string, a symbol, or an array of string or symbol.
 

data/lib/web_translate_it/configuration.rb

@@ -18,6 +18,7 @@ module WebTranslateIt
       self.path           = root_path
       self.logger         = logger
       if File.exist?(File.expand_path(path_to_config_file, path))
+        load_project_id
         self.api_key        = ENV.fetch('WTI_PROJECT_API_KEY') { configuration['api_key'] }
         self.before_pull    = configuration['before_pull']
         self.after_pull     = configuration['after_pull']
@@ -95,7 +96,7 @@ module WebTranslateIt
 
     # Convenience method which returns the endpoint for fetching a list of locales for a project.
     def api_url
-      Connection::PROJECT_PATH
+      Connection.project_path
     end
 
     # Returns a logger. If RAILS_DEFAULT_LOGGER is defined, use it, else, define a new logger.
@@ -108,11 +109,24 @@ module WebTranslateIt
     end
 
     def configuration
-      @configuration ||= YAML.safe_load(parse_erb_in_configuration)
+      @configuration ||= YAML.safe_load(rendered_configuration)
     end
 
     private
 
+    # Fails early, with a clear message, on a project id that is not numeric.
+    def load_project_id
+      ProjectIdText.validate!(rendered_configuration)
+      Connection.project_id = configuration['project_id']
+      Connection.project_id
+    rescue ArgumentError => e
+      abort StringUtil.failure("\n#{e.message}")
+    end
+
+    def rendered_configuration
+      @rendered_configuration ||= parse_erb_in_configuration
+    end
+
     def load_project_data # rubocop:todo Metrics/AbcSize
       project = JSON.parse(WebTranslateIt::Project.fetch_info(api_key))['project']
       self.ignore_locales = locales_to_ignore(configuration)

data/lib/web_translate_it/connection.rb

@@ -7,16 +7,58 @@ module WebTranslateIt
     # The API resolves `current` to the project the bearer token belongs to.
     PROJECT_PATH = '/api/projects/current'
 
+    ORGANIZATION_TOKEN_HINT = 'No project matched this API token at /api/projects/current. Either the project doesn\'t accept API tokens yet ' \
+                              '(a manager can switch it in Project settings → API), or this is an organization token: ' \
+                              "set %<setting>s to the project's numeric id."
+    # The error the API answers when authentication finds no record for the token.
+    AUTHENTICATION_NOT_FOUND = 'No project found for this API token'
+
     @debug = false
 
     class << self
 
       attr_reader :debug
 
+      # The hint is printed at most once per process.
+      attr_accessor :organization_token_hint_printed
+
+      # `wti init` rewrites .wti, so its hint mentions WTI_PROJECT_ID only.
+      attr_accessor :hint_without_config_file
+
+      # Numeric project id from the configuration file. Organization tokens can only
+      # reach a project by its id. WTI_PROJECT_ID takes precedence over it.
+      def project_id=(value)
+        @project_id = normalize_project_id(value)
+      end
+
+      def project_id
+        normalize_project_id(ENV.fetch('WTI_PROJECT_ID', nil), 'WTI_PROJECT_ID') || @project_id
+      end
+
+      # `/api/projects/<id>` when a project id is set, `/api/projects/current` otherwise.
+      def project_path
+        id = project_id
+        id ? "/api/projects/#{id}" : PROJECT_PATH
+      end
+
+      private
+
+      def normalize_project_id(value, source = 'project_id')
+        id = value.to_s.strip
+        return nil if id.empty?
+        raise ArgumentError, "Error: #{source} must be the numeric id of your project (digits only, no leading zero), got `#{id}`." unless id.match?(/\A[1-9]\d*\z/)
+
+        id
+      end
+
     end
 
     attr_reader :api_key, :http_connection
 
+    def project_path
+      self.class.project_path
+    end
+
     #
     # Initialize and yield a HTTPS Keep-Alive connection to WebTranslateIt.com
     #
@@ -75,7 +117,28 @@ module WebTranslateIt
       request['Authorization'] = "Bearer #{api_key}"
       request.body = body if body
       yield request if block_given?
-      http_connection.request(request)
+      response = http_connection.request(request)
+      print_organization_token_hint(path, response) if response.code.to_i == 404
+      response
+    end
+
+    # `current` answers 404 to organization tokens, which can only address a project by id.
+    # Only the authentication error counts: an ordinary resource 404 says nothing about the token.
+    def print_organization_token_hint(path, response)
+      return if self.class.organization_token_hint_printed
+      return unless path.start_with?(PROJECT_PATH) && api_key.to_s.start_with?('wti_')
+      return unless authentication_not_found?(response)
+
+      self.class.organization_token_hint_printed = true
+      setting = self.class.hint_without_config_file ? '`WTI_PROJECT_ID`' : '`project_id` in .wti (or `WTI_PROJECT_ID`)'
+      warn format(ORGANIZATION_TOKEN_HINT, setting: setting)
+    end
+
+    def authentication_not_found?(response)
+      body = JSON.parse(response.body.to_s)
+      body.is_a?(Hash) && body['error'].to_s.start_with?(AUTHENTICATION_NOT_FOUND)
+    rescue JSON::ParserError
+      false
     end
 
   end

data/lib/web_translate_it/project.rb

@@ -7,13 +7,13 @@ module WebTranslateIt
     def self.fetch_info(api_key)
       Concurrency.with_retries do
         WebTranslateIt::Connection.new(api_key) do |conn|
-          return HttpResponse.handle_response(conn.get(Connection::PROJECT_PATH))
+          return HttpResponse.handle_response(conn.get(Connection.project_path))
         end
       end
     end
 
     def self.fetch_stats(api_key, file_id = nil)
-      url = file_id.nil? ? "#{Connection::PROJECT_PATH}/stats" : "#{Connection::PROJECT_PATH}/stats?file=#{file_id}"
+      url = file_id.nil? ? "#{Connection.project_path}/stats" : "#{Connection.project_path}/stats?file=#{file_id}"
       Concurrency.with_retries do
         WebTranslateIt::Connection.new(api_key) do |conn|
           return HttpResponse.handle_response(conn.get(url))
@@ -24,7 +24,7 @@ module WebTranslateIt
     # Fetch every language file of a project in a single request, as a zip
     # archive. Pass a locale to narrow the archive down to that locale.
     def self.fetch_zip(connection, locale: nil)
-      url = "#{Connection::PROJECT_PATH}/zip_file"
+      url = "#{Connection.project_path}/zip_file"
       url += "?locale=#{URI.encode_www_form_component(locale)}" if locale
       Concurrency.with_retries do
         HttpResponse.handle_response(connection.get(url))
@@ -33,14 +33,14 @@ module WebTranslateIt
 
     def self.create_locale(connection, locale_code)
       Concurrency.with_retries do
-        response = connection.post("#{Connection::PROJECT_PATH}/locales") { |req| req.set_form_data({'id' => locale_code}, ';') }
+        response = connection.post("#{Connection.project_path}/locales") { |req| req.set_form_data({'id' => locale_code}, ';') }
         HttpResponse.handle_response(response)
       end
     end
 
     def self.delete_locale(connection, locale_code)
       Concurrency.with_retries do
-        HttpResponse.handle_response(connection.delete("#{Connection::PROJECT_PATH}/locales/#{locale_code}"))
+        HttpResponse.handle_response(connection.delete("#{Connection.project_path}/locales/#{locale_code}"))
       end
     end
 

data/lib/web_translate_it/term_translation.rb

@@ -43,7 +43,7 @@ module WebTranslateIt
 
     def update
       Concurrency.with_retries do
-        HttpResponse.handle_response(connection.put("#{Connection::PROJECT_PATH}/terms/#{id}/locales/#{locale}/translations/#{id}", body: to_json))
+        HttpResponse.handle_response(connection.put("#{Connection.project_path}/terms/#{id}/locales/#{locale}/translations/#{id}", body: to_json))
       end
     end
 

data/lib/web_translate_it/translation_base.rb

@@ -30,7 +30,7 @@ module WebTranslateIt
     def assign_attributes(_params); end
 
     def translation_path
-      "#{Connection::PROJECT_PATH}/#{self.class.parent_resource_path}/#{parent_id}/locales/#{locale}/translations"
+      "#{Connection.project_path}/#{self.class.parent_resource_path}/#{parent_id}/locales/#{locale}/translations"
     end
 
   end

data/lib/web_translate_it/translation_file.rb

@@ -188,15 +188,15 @@ module WebTranslateIt
 
     # Convenience method which returns the URL of the API endpoint for a locale.
     def api_url
-      "#{Connection::PROJECT_PATH}/files/#{id}/locales/#{locale}"
+      "#{Connection.project_path}/files/#{id}/locales/#{locale}"
     end
 
     def api_url_for_create
-      "#{Connection::PROJECT_PATH}/files"
+      "#{Connection.project_path}/files"
     end
 
     def api_url_for_delete
-      "#{Connection::PROJECT_PATH}/files/#{id}"
+      "#{Connection.project_path}/files/#{id}"
     end
 
     def local_checksum

data/lib/web_translate_it/util/http_response.rb

@@ -40,6 +40,14 @@ module WebTranslateIt
       request.add_field('Content-Type', 'application/json')
     end
 
+    FRIENDLY_MESSAGES = {
+      'legacy_token_disabled' => 'This project only accepts API tokens now. Create a token in Project settings → API ' \
+                                 '(or Account settings → API tokens) and put it in WTI_PROJECT_API_KEY / `api_key` in .wti.',
+      'invalid_token' => 'This API token was revoked or has expired. Create a new token in Project settings → API ' \
+                         '(or Account settings → API tokens) and put it in WTI_PROJECT_API_KEY / `api_key` in .wti.',
+      'insufficient_scope' => 'This is a read-only token; this command needs a read & write token.'
+    }.freeze
+
     def self.raise_on_error!(response)
       code = response.code.to_i
       raise_on_rate_limit!(response) if code == 429
@@ -54,7 +62,10 @@ module WebTranslateIt
     end
 
     def self.error_message(response)
-      JSON.parse(response.body)['error']
+      body = JSON.parse(response.body)
+      return response.body.to_s unless body.is_a?(Hash)
+
+      FRIENDLY_MESSAGES.fetch(body['code'], nil) || body['error'] || response.body.to_s
     rescue StandardError
       response.body.to_s
     end

data/lib/web_translate_it/util/project_id_text.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module WebTranslateIt
+
+  # Checks the `project_id` of a configuration file as written. YAML turns `012` or `0x1F`
+  # into a different Integer, which can no longer be told from a plain id, so the value is
+  # read from the parse tree instead: every spelling of the key (`project_id :`,
+  # `"project_id":`) is seen, and the last one wins when the key is repeated, as it does
+  # for YAML.safe_load.
+  module ProjectIdText
+
+    NULLS = %w[~ null Null NULL].freeze
+
+    def self.validate!(yaml_text)
+      node = node_for(yaml_text)
+      return if node.nil? || null?(node)
+      return if node.is_a?(Psych::Nodes::Scalar) && node.value.strip.match?(/\A[1-9]\d*\z/)
+
+      raw = node.is_a?(Psych::Nodes::Scalar) ? node.value.strip : node.class.name.split('::').last.downcase
+      raise ArgumentError, "Error: project_id must be the numeric id of your project (digits only, no leading zero), got `#{raw}`."
+    end
+
+    def self.node_for(yaml_text)
+      root = YAML.parse(yaml_text)&.root
+      return unless root.is_a?(Psych::Nodes::Mapping)
+
+      root.children.each_slice(2).reverse_each.find { |key, _| key.is_a?(Psych::Nodes::Scalar) && key.value == 'project_id' }&.last
+    end
+
+    def self.null?(node)
+      node.is_a?(Psych::Nodes::Scalar) && !node.quoted && (node.value.strip.empty? || NULLS.include?(node.value.strip))
+    end
+
+  end
+
+end

data/lib/web_translate_it.rb

@@ -21,6 +21,7 @@ require 'web_translate_it/util/spinner'
 require 'web_translate_it/util/http_response'
 require 'web_translate_it/util/concurrency'
 require 'web_translate_it/util/prompt'
+require 'web_translate_it/util/project_id_text'
 require 'web_translate_it/configuration'
 require 'web_translate_it/translation_file'
 require 'web_translate_it/api_resource'

data/readme.md

@@ -59,7 +59,18 @@ Check `wti --help` for help.
 
 `proj_pvt_V8skdjsdDDA4` is the API token, which you can find in your project settings.
 
-If you’d like to specify another path for your configuration file, you can use `wti init`. This command will ask you to enter your project API token and where to save the configuration file (by default it will create a `.wti` in your project root directory).
+### API tokens
+
+`wti` accepts these credentials, passed to `wti init`, in `WTI_PROJECT_API_KEY` or as `api_key` in `.wti`. Legacy project API keys keep working. API tokens (`wti_…`) have two independent properties:
+
+* **Kind**: a **personal** token acts as you, within the roles you hold; an **integration** token is not tied to a person, so it keeps working when someone leaves.
+* **Owner**: a **project** token belongs to one project, and `wti` finds the project from the token. An **organization** token belongs to an organization, and can't tell which project you mean, so you also have to give the project's numeric id (see below).
+
+A token has the format `wti_<kind><scope>_…`: the first letter after `wti_` is the kind (`p` personal, `i` integration) and the second is the scope (`r` read-only, `w` read & write). So `wti_pr_…` is a personal read-only token and `wti_iw_…` an integration read & write token. A read-only token can pull but not push.
+
+`wti_` tokens only work once the project is set to "Both" or "API tokens only" in Project settings → API; for organization tokens, the organization must be set the same way too. Until then the API answers 404. A project set to "API tokens only" refuses the legacy project API keys, and `wti` tells you to create a token in Project settings → API (or Account settings → API tokens).
+
+If you’d like to specify another path for your configuration file, you can use `wti init`. This command will ask you to enter your API token and where to save the configuration file (by default it will create a `.wti` in your project root directory).
 
 ### Keeping the API token out of `.wti`
 
@@ -73,6 +84,21 @@ api_key: <%= ENV['WTI_PROJECT_API_KEY'] %>
 
 `.wti` is read through ERB, so you can point `api_key` at any environment variable this way. In CI, store the token as a secret and expose it as `WTI_PROJECT_API_KEY`.
 
+### Organization tokens: `project_id`
+
+With an organization token, add the numeric id of the project to `.wti`:
+
+``` yaml
+api_key: <%= ENV['WTI_PROJECT_API_KEY'] %>
+project_id: 12345
+```
+
+or set the `WTI_PROJECT_ID` environment variable. Like `WTI_PROJECT_API_KEY`, `WTI_PROJECT_ID` overrides every configuration file in that shell. If `WTI_PROJECT_ID` is set when you run `wti init`, the generated `.wti` includes `project_id`.
+
+Write the id as plain digits, without a leading zero: `wti` rejects anything else. If you get a "not found" error with a `wti_` token, either the project doesn't accept API tokens yet or you need `project_id`.
+
+Library users: `project_id` is process-wide. The last `WebTranslateIt::Configuration` loaded, or the `WTI_PROJECT_ID` environment variable, wins, so don't load configurations for different projects with organization tokens in the same process.
+
 Now you’re all set and you can use the `wti` commands on your project.
 
 ## Using on multiple projects

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: web_translate_it
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Edouard Briere
@@ -104,6 +104,7 @@ files:
 - lib/web_translate_it/util/concurrency.rb
 - lib/web_translate_it/util/hash_util.rb
 - lib/web_translate_it/util/http_response.rb
+- lib/web_translate_it/util/project_id_text.rb
 - lib/web_translate_it/util/prompt.rb
 - lib/web_translate_it/util/spinner.rb
 - lib/web_translate_it/util/string_util.rb