crowdin-api 0.4.0 → 1.0.0

data/README.md

@@ -1,329 +1,169 @@
-# Crowdin::API
+[<p align='center'><img src='https://support.crowdin.com/assets/logos/crowdin-dark-symbol.png' data-canonical-src='https://support.crowdin.com/assets/logos/crowdin-dark-symbol.png' width='200' height='200' align='center'/></p>](https://crowdin.com)
 
-A Ruby interface to the Crowdin API.
+# Crowdin Ruby client
 
-For more about the Crowdin API see <https://crowdin.com/page/api>.
+The Crowdin Ruby client is a lightweight interface to the Crowdin API v2. It provides common services for making API requests.
 
-To experiment with that code, run `bin/console` for an interactive prompt.
+Crowdin API is a full-featured RESTful API that helps you to integrate localization into your development process. The endpoints that we use allow you to easily make calls to retrieve information and to execute actions needed.
 
-> **WARNING**: This is a development version: It contains the latest changes, but may also have severe known issues, including crashes and data loss situations. In fact, it may not work at all.
+For more about Crowdin API v2 see the documentation:
+- [Crowdin](https://support.crowdin.com/api/v2/)
+- [Crowdin Enterprise](https://support.crowdin.com/enterprise/api/)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```
-gem 'crowdin-api'
-```
-
-And then execute:
-```
-$ bundle
-```
-
-Or install it yourself as:
-```
-$ gem install crowdin-api
-```
-
-## Usage
-
-Start by creating a connection to Crowdin with your credentials:
-
-Please note that almost all API calls require the `Project Identifier` and `Project API Key`.
-
-```ruby
-require 'crowdin-api'
-require 'logger'
-
-crowdin = Crowdin::API.new(api_key: API_KEY, project_id: PROJECT_ID)
-crowdin.log = Logger.new $stderr
-```
-
-As well there are several API methods (`get_projects`, `create_project`) that require `User API Key` instead of regular `Project API Key`.
-
-```ruby
-crowdin = Crowdin::API.new(account_key: ACCOUNT_KEY)
-```
+### Status
 
-Now you can make requests to the api.
+[![Gem](https://img.shields.io/gem/v/crowdin-api?logo=ruby&cacheSeconds=1800)](https://rubygems.org/gems/crowdin-api)
+[![Gem](https://img.shields.io/gem/dt/crowdin-api?cacheSeconds=1800)](https://rubygems.org/gems/crowdin-api)
+[![Gem](https://img.shields.io/gem/dtv/crowdin-api?cacheSeconds=1800)](https://rubygems.org/gems/crowdin-api)
 
-### Add File
+[![Test and Lint](https://github.com/crowdin/crowdin-api-client-ruby/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/crowdin/crowdin-api-client-ruby/actions/workflows/test-and-lint.yml)
+[![Build and Publish](https://github.com/crowdin/crowdin-api-client-ruby/actions/workflows/build-and-publish.yml/badge.svg)](https://github.com/crowdin/crowdin-api-client-ruby/actions/workflows/build-and-publish.yml)
+[![codecov](https://codecov.io/gh/crowdin/crowdin-api-client-ruby/branch/master/graph/badge.svg?token=OJsyJwQbFM)](https://codecov.io/gh/crowdin/crowdin-api-client-ruby)
 
-Add new file to Crowdin project.
+[![GitHub issues](https://img.shields.io/github/issues/crowdin/crowdin-api-client-ruby?cacheSeconds=1800)](https://github.com/crowdin/crowdin-api-client-ruby/issues)
+[![GitHub](https://img.shields.io/github/license/crowdin/crowdin-api-client-ruby?cacheSeconds=18000)](https://github.com/crowdin/crowdin-api-client-ruby/blob/main/LICENSE)
 
-Documentation:  <https://crowdin.com/page/api/add-file>.
+## Table of Contents
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+  * [Initialization](#initialization)
+  * [How to call methods](#how-to-call-methods)
+  * [Command-Line Client](#command-line-client)
+* [Seeking Assistance](#seeking-assistance)
+* [Contributing](#contributing)
+* [License](#license)
 
-First parameter is array of files that should be added to Crowdin project.
-Every file is hash:
-* `:dest` - file name with path in Crowdin project (required)
-* `:source` - file that should be added (required)
-* `:title` - string that defines title for uploaded file (optional)
-* `:export_pattern` - string that defines name of resulted file (optional)
-
-Optional params:
-* `:branch` - a branch name (optional)
-
-**NOTE!** 20 files max are allowed to upload per one time file transfer.
-
-```ruby
-crowdin.add_file(
-  files = [
-    { dest: '/directory/array.xml', source: 'array.xml', export_pattern: '/values-%two_letters_code%/%original_file_name%' },
-    { dest: 'strings.xml', source: 'strings.xml', title: 'Texts in Application' }
-], type: 'android')
-```
-
-### Update File
-
-Upload fresh version of your localization file.
-
-Documentation <https://crowdin.com/page/api/update-file>
-
-First parameter is array of files that should be updated in Crowdin project.
-Every file is hash:
-* `:dest` - file name with path in Crowdin project (required)
-* `:source` - uploaded file (required)
-* `:title` - title for uploaded file (optional)
-* `:export_pattern` - string that defines name of resulted file (optional)
-
-Optional params:
-* `:branch` - a branch name (optional)
-
-**NOTE!** 20 files max are allowed to upload per one time file transfer.
+## Installation
 
-```ruby
-crowdin.update_file(
-  files = [
-    { :dest => '/directory/array.xml', :source => 'array.xml', :export_pattern => '/values-%two_letters_code%/%original_file_name%'},
-    { :dest => 'strings.xml', :source => 'strings.xml' }
-])
+Add this line to your application's Gemfile:
 
+```gemfile
+gem 'crowdin-api', '~> 1.0.0'
 ```
 
-### Delete File
-
-Remove file from Crowdin project.
-
-Documentation <https://crowdin.com/page/api/delete-file>
+And then execute:
 
-```ruby
-crowdin.delete_file('strings.xml')
+```console
+bundle install
 ```
 
-### Create Directory
-
-Create a new directory in Crowdin project.
-
-First parameter `name` - full directory path that should be created (e.g. /MainPage/AboutUs) (required)
-
-Optional params:
-* `:is_branch` - create new branch. Valid values - `'0'`, `'1'`. Only when create root directory.
-* `:branch` - a branch name.
-
-Documentation: <https://crowdin.com/page/api/add-directory>
+Or install it yourself as:
 
-```ruby
-crowdin.add_directory('dirname')
+```console
+gem install crowdin-api
 ```
 
-Create a new branch:
-
-```ruby
-crowdin.add_directory('master', is_branch: '1')
-```
+---
 
-### Delete Directory
+:bookmark_tabs: For versions *0.6.0* and lower see the [branch api/v1](https://github.com/crowdin/crowdin-api-client-ruby/tree/api/v1). Please note that these versions are no longer supported.
 
-Remove directory with nested files from Crowdin project.
+:exclamation: Migration from version *0.6.0* to *1.x.x* requires changes in your code.
 
-Optional params:
-* `:branch` - a branch name (optional)
+---
 
-Documentation: <https://crowdin.com/page/api/delete-directory>
+## Quick start
 
+### Initialization
 ```ruby
-crowdin.delete_directory('dirname')
-```
-
-### Change Directory
-
-Rename or change directory attributes.
-
-Documentation: <https://crowdin.com/page/api/change-directory>
-
-First parameter `name` - full directory path that should be modified (e.g. /MainPage/AboutUs) (required)
-
-Optional params:
-* `:new_name` - new directory name
-* `:title` - new directory title to be displayed in Crowdin UI
-* `:export_pattern` - new direcrory export pattern. Is used to create directory name and path in resulted translations bundle.
-* `:branch` - a branch name.
+require 'crowdin-api'
 
+# Create a new Crowdin Client object.
+crowdin = Crowdin::Client.new do |config|
+  config.api_token = 'YourApiToken'
+end
+# or you can create Enterprise instance by specify your organization_domain
+crowdin = Crowdin::Client.new do |config|
+  config.api_token = 'YourEnterpriseApiToken'
+  config.organization_domain = 'YourOrganizationDomain'
+end
 
-When renaming directory the path can not be changed (it means `new_name` parameter can not contain path, name only).
+# Also you can specify project_id to handle it in methods
 
-```ruby
-crowdin.change_directory('/MainPage/AboutUs', new_name: 'AboutCompany')
+# All Crowdin Client config options:
+crowdin = Crowdin::Client.new do |config|
+  config.api_token = 'YourApiToken' # [String] required
+  config.organization_domain = 'YourOrganizationDomain' # [String] optional
+  config.project_id = 'YourProjectId' # [Integer] nil by default
+  config.enable_logger = true # [Boolean] false by default
+end
 ```
 
-### Upload Translations
-
-Upload existing translations to your Crowdin project.
-
-Documentation: <https://crowdin.com/page/api/upload-translation>
-
-First parameter is array of translated files that should be added to Crowdin project.
-Every file is hash:
-* `:dest` - file names in Crowdin (required)
-* `:source` - uploaded translation (required)
-
-Second parameter is target language.
-With a single call it's possible to upload translations for several files but only into one of the languages.
-Check [complete list of Crowdin language codes](https://crowdin.com/page/api/language-codes) that can be used.
+To generate a new token in Crowdin, follow these steps:
+- Go to *Account Settings* > *API* tab, *Personal Access Tokens* section, and click *New Token*.
+- Specify *Token Name* and click *Create*.
 
-Optional params:
-* `:import_duplicates` - defines whether to add translation if there is the same translation previously added (default: false)
-* `:import_eq_suggestions` - defines whether to add translation if it is equal to source string at Crowdin (default: false)
-* `:auto_approve_imported` - mark uploaded translations as approved (default: false)
-* `:branch` - a branch name (default: nil)
+To generate a new token in Crowdin Enterprise, follow these steps:
+- Go to *Account Settings* > *Access tokens* tab and click *New token*.
+- Specify *Token Name*, select *Scopes* and *Projects*, click *Create*.
 
-**NOTE!** 20 files max are allowed to upload per one time file transfer.
+### How to call methods
 
 ```ruby
-crowdin.upload_translation(
-  files = [
-    { :dest => 'strings.xml', :source => 'strings_uk.xml' },
-    { :dest => 'array.xml', :source => 'array_uk.xml' }
-  ],
-  language = 'uk',
-  params = {:import_duplicates => true}
-)
-```
-
-### Download Translations
+# Create Project
+project = crowdin.add_project(name: your_project_name, sourceLanguageId: your_language_id)
 
-Download last exported translation package (one target language or all languages as one zip file).
+# Get list of Projects
+projects = client.list_projects
 
-Documentation: <https://crowdin.com/page/api/download>
+# Get specified project
+project = client.get_project(your_project_id)
 
-First parameter is the language of translation you need or download `all` of them at once.
+# Get list of Projects with offset and limit
+projects = client.list_projects(offset: 10, limit: 20)
 
-Optional params:
-* `:output` - a name of ZIP file with translations
-* `:branch` - a branch name (default: nil)
+# Add Storage
+adding_storage_response = crowdin.add_storage(File.open('YourFilename.extension'))
+# or you can specify only filename
+adding_storage_response = crowdin.add_storage('YourFilename.extension')
 
+# Download file
+filename = crowdin.download_file(your_destination, your_file_id, your_project_id)
+# your_destination - filename or full path to file
+# project_id is optional, as it can be initialized with a Crowdin Client
 
-```ruby
-crowdin.download_translation('ru', :output => '/path/to/download/ru_RU.zip')
+# File revisions
+file_revisions = crowdin.list_file_revisions(your_file_id, { limit: 10, project_id: your_project_id })
+# project_id is optional, as it can be initialized with a Crowdin Client
 ```
 
-### Translation Status
-
-Track overall translation and proofreading progress of each target language.
+### Command-Line Client
 
-Documentation: <https://crowdin.com/page/api/status>
+The Crowdin Ruby client support crowdin-console, where you can test endpoints easier
 
-```ruby
-crowdin.translations_status
+```console
+bundle exec crowdin-console --enable-logger --api-token API_TOKEN --project-id PROJECT_ID
 ```
 
-### Project Info
-
-Shows project details and meta information (last translations date, currently uploaded files, target languages etc..).
-
-Documentation: <https://crowdin.com/page/api/info>
+Or Crowdin Enterprise
 
-```ruby
-crowdin.project_info
+```console
+bundle exec crowdin-console --enable-logger --enterprise --api-token API_TOKEN --organization-domain YOUR_DOMAIN
 ```
 
-### Export Translations
-
-Build ZIP archive with the latest translations.
-
-**Note!** This method can be invoked only once per 30 minutes (there is no such restriction for organization plans).
-
-Also API call will be ignored if there were no changes in the project since previous export.
-You can see whether ZIP archive with latest translations was actually build by status attribute (`built` or `skipped`) returned in response.
-
-Optional params:
-* `:branch` - a branch name (default: nil)
-
-Documentation: <https://crowdin.com/page/api/export>
+When execute you'll have IRB console with configured *@crowdin* instance
 
-```ruby
-crowdin.export_translations
 ```
-
-### Account Projects
-
-Get Crowdin Project details.
-
-**Important:** This API method requires `Account API Key`. This key can not be found on your profile pages.
-
-Documentation: <https://crowdin.com/page/api/get-projects>
-
-```ruby
-crowdin = Crowdin::API.new(account_key: ACCOUNT_KEY)
-crowdin.get_projects(login = 'YourCrowdinAccount')
+> @crowdin.list_projects
 ```
 
-### Create Project
-
-Create Crowdin project.
-
-**Important:** This API method requires `Account API Key`. This key can not be found on your profile pages.
-
-Documentation: <https://crowdin.com/page/api/create-project>
-
-### Edit Project
-
-Documentation: <https://crowdin.com/page/api/edit-project>
-
-### Delete Project
+## Seeking Assistance
 
-Documentation: <https://crowdin.com/page/api/delete-project>
+If you find any problems or would like to suggest a feature, please read the [How can I contribute](/CONTRIBUTING.md#how-can-i-contribute) section in our contributing guidelines.
 
-### Download Glossary
-
-Documentation: <https://crowdin.com/page/api/download-glossary>
-
-### Upload Glossary
-
-Documentation: <https://crowdin.com/page/api/upload-glossary>
-
-### Download TM
-
-Documentation: <https://crowdin.com/page/api/download-tm>
-
-### Upload TM
-
-Documentation: <https://crowdin.com/page/api/upload-tm>
-
-### Supported Languages
-
-Documentation: <https://crowdin.com/page/api/supported-languages>
-
-## Supported Rubies
-
-Tested with the following Ruby versions:
-
-- MRI 2.2.1
-- JRuby 9.0.0.0
+Need help working with Crowdin Ruby client or have any questions? [Contact](https://crowdin.com/contacts) Customer Success Service.
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## License and Author
+If you want to contribute please read the [Contributing](/CONTRIBUTING.md) guidelines.
 
-Author: Anton Maminov (anton.maminov@gmail.com)
+## License
 
-Copyright: 2012-2015 [crowdin.com](https://crowdin.com/)
+<pre>
+The Crowdin Ruby Client is licensed under the MIT License.
+See the LICENSE.md file distributed with this work for additional 
+information regarding copyright ownership.
 
-This library is distributed under the MIT license. Please see the LICENSE file.
+Except as contained in the LICENSE file, the name(s) of the above copyright
+holders shall not be used in advertising or otherwise to promote the sale,
+use or other dealings in this Software without prior written authorization.
+</pre>

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core'
+
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  # Ignored
+end
+
+if defined?(RSpec)
+  desc 'Run specs'
+  RSpec::Core::RakeTask.new(:spec) do |spec|
+    spec.pattern = FileList['spec/**/*_spec.rb']
+  end
+
+  task default: %i[spec]
+end

data/bin/crowdin-console

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'crowdin-api'
+require 'optparse'
+
+# You can specify your arguments when execute this script
+#
+# Type bundle exec crowdin-console --help for more available arguments
+#
+# Example:
+#
+#  bundle exec crowdin-console --enable-logger --api-token YOUR_API_TOKEN --project-id YOUR_PROJECT_ID
+#
+# or Enterpise API
+#
+#  bundle exec crowdin-console --enterprise --api-token YOUR_ENTERPRISE_API_TOKEN --organization-domain YOUR_DOMAIN
+
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: ./bin/crowdin-console --enable-logger --api-token YOUR_API_TOKEN ..'
+
+  opts.on('--enterprise', 'Enterprise API')                      { |v| options[:enterprise] = v }
+  opts.on('--api-token TOKEN', 'API Token')                      { |v| options[:api_token] = v }
+  opts.on('--organization-domain DOMAIN', 'Organization Domain') { |v| options[:organization_domain] = v }
+  opts.on('--prohject-id ID', 'Project ID')                      { |v| options[:project_id] = v }
+  opts.on('--enable-logger', 'Enable logger')                    { |v| options[:enable_logger] = v }
+end.parse!
+
+options[:api_token] || raise(ArgumentError, '--api-token argument is required')
+
+if options[:enterprise]
+  options[:organization_domain] || raise(ArgumentError, '--organization-domain option is required for Enterprise mode')
+
+  @crowdin = Crowdin::Client.new do |config|
+    config.api_token           = options[:api_token]
+    config.organization_domain = options[:organization_domain]
+    config.enable_logger       = options[:enable_logger]       || false
+    config.project_id          = options[:project_id]          || nil
+  end
+else
+  @crowdin = Crowdin::Client.new do |config|
+    config.api_token     = options[:api_token]
+    config.enable_logger = options[:enable_logger] || false
+    config.project_id    = options[:project_id]    || nil
+  end
+end
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/crowdin-api.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require File.expand_path('lib/crowdin-api/client/version', __dir__)
+
+Gem::Specification.new do |gem|
+  gem.name        = 'crowdin-api'
+  gem.version     = Crowdin::Client::VERSION
+  gem.authors     = ['Crowdin']
+  gem.email       = ['support@crowdin.net']
+  gem.homepage    = 'https://github.com/crowdin/crowdin-api/'
+  gem.summary     = 'Client library to manage translations on Crowdin'
+  gem.description = 'Ruby Client for the Crowdin API. Documentation - https://support.crowdin.com/api/v2/.'
+  gem.license     = 'MIT'
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ['lib']
+  gem.bindir        = 'bin'
+  gem.executables   << 'crowdin-console'
+
+  gem.add_runtime_dependency 'open-uri', '>= 0.1.0', '< 0.2.0'
+  gem.add_runtime_dependency 'rest-client', '>= 2.0.0', '< 2.1.0'
+
+  gem.add_development_dependency 'bundler', '~> 2.2', '>= 2.2.32'
+  gem.add_development_dependency 'rake', '~> 13.0', '>= 13.0.6'
+  gem.add_development_dependency 'rspec', '~> 3.10'
+  gem.add_development_dependency 'rubocop', '~> 1.23'
+  gem.add_development_dependency 'sinatra', '~> 2.1'
+  gem.add_development_dependency 'webmock', '~> 3.14'
+end

data/lib/crowdin-api/api-resources/languages.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Crowdin
+  module ApiResources
+    module Languages
+      def list_languages(query = {})
+        request = Web::Request.new(
+          self,
+          :get,
+          '/languages',
+          query
+        )
+
+        request.perform
+      end
+
+      # Add custom language.
+      #
+      # === Parameters
+      #
+      # * +:name+ [String] - Language name
+      # * +:code+ [String] - Custom language code
+      # * +:localeCode+ [String] - Custom language locale code
+      # * +:textDirection+ [String ltr/rtl] - Text direction in custom language
+      # * +:pluralCategoryNames+ [String] - Array with category names
+      # * +:threeLettersCode+ [String] - Custom language 3 letters code. Format: ISO 6393 code
+      #
+      # === Example
+      #
+      #  crowdin.add_custom_language(name: 'your_name', code: 'your_code' ..)
+      #
+      def add_custom_language(query = {})
+        request = Web::Request.new(
+          self,
+          :post,
+          '/languages',
+          query
+        )
+
+        request.perform
+      end
+
+      def get_language(language_id = nil)
+        language_id || raise(ArgumentError, ':language_id is required')
+
+        request = Web::Request.new(
+          self,
+          :get,
+          "/languages/#{language_id}"
+        )
+
+        request.perform
+      end
+
+      def delete_custom_language(language_id = nil)
+        language_id || raise(ArgumentError, ':language_id is required')
+
+        request = Web::Request.new(
+          self,
+          :delete,
+          "/languages/#{language_id}"
+        )
+
+        request.perform
+      end
+
+      def edit_custom_language(language_id = nil)
+        language_id || raise(ArgumentError, ':language_id is required')
+
+        request = Web::Request.new(
+          self,
+          :patch,
+          "/languages/#{language_id}",
+          query
+        )
+
+        request.perform
+      end
+    end
+  end
+end