Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/crowdin/crowdin-api-client-ruby
Ruby client library for Crowdin API
https://github.com/crowdin/crowdin-api-client-ruby
api hacktoberfest i18n ruby sdk
Last synced: 2 days ago
JSON representation
Ruby client library for Crowdin API
- Host: GitHub
- URL: https://github.com/crowdin/crowdin-api-client-ruby
- Owner: crowdin
- License: mit
- Created: 2012-09-04T20:31:56.000Z (about 12 years ago)
- Default Branch: main
- Last Pushed: 2024-10-28T08:22:15.000Z (16 days ago)
- Last Synced: 2024-10-28T10:09:17.623Z (16 days ago)
- Topics: api, hacktoberfest, i18n, ruby, sdk
- Language: Ruby
- Homepage: https://rubygems.org/gems/crowdin-api
- Size: 544 KB
- Stars: 57
- Watchers: 6
- Forks: 16
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Crowdin Ruby client
The Crowdin Ruby client is a lightweight interface to the Crowdin API. It provides common services for making API requests.
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.
[**`API Client Docs`**](http://crowdin.github.io/crowdin-api-client-ruby/) |
[**`Crowdin API`**](https://developer.crowdin.com/api/v2/) |
[**`Crowdin Enterprise API`**](https://developer.crowdin.com/enterprise/api/v2/)
[](https://rubygems.org/gems/crowdin-api)
[](https://rubygems.org/gems/crowdin-api)
[](https://rubygems.org/gems/crowdin-api)
[](https://github.com/crowdin/crowdin-api-client-ruby/actions/workflows/test-and-lint.yml)
[](https://codecov.io/gh/crowdin/crowdin-api-client-ruby)
[](https://github.com/crowdin/crowdin-api-client-ruby/blob/main/LICENSE)
## Requirements
* Ruby >= 2.4
## Installation
Add this line to your application's Gemfile:
```gemfile
gem 'crowdin-api', '~> 1.12.0'
```
And then execute:
```console
bundle install
```
Or install it yourself as:
```console
gem install crowdin-api
```
## Quick start
### Initialization
```ruby
require 'crowdin-api'
# Initialize a new Client instance with config options
crowdin = Crowdin::Client.new do |config|
config.api_token = 'YourApiToken'
end
# Or you can initialize Enterprise Client instance by specifying your
# organization_domain in config options
crowdin = Crowdin::Client.new do |config|
config.api_token = 'YourEnterpriseApiToken'
config.organization_domain = 'YourOrganizationDomain'
end
# Note: we use full specified organization domain if that includes '.com'
# config.organization_domain = your_domain -> https://your_domain.api.crowdin.com
# config.organization_domain = your_domain.com -> https://your_domain.com
# All supported Crowdin Client config options now:
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
config.request_timeout = 60 # [nil, Integer] disabled by default
end
# Note: Client will initialize default Logger instance if you have specify
# enable_logger to true, you can change it by crowdin.logger = YourLogger
# Also you can specify proxy by adding it to ENV['http_proxy'] before Client initialization
```
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*.
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*.
### Usage
```ruby
# Create Project
project = crowdin.add_project(name: your_project_name, sourceLanguageId: your_language_id)
# Get list of Projects
projects = crowdin.list_projects
# Get list of Projects with offset and limit
projects = crowdin.list_projects(offset: 10, limit: 20)
# Get specified project
project = crowdin.get_project(your_project_id)
# Edit project
project = crowdin.edit_project(project_id, [{ op: 'replace',
path: '/name',
value: 'your_new_project_name' }])
# Add Storage
storage = crowdin.add_storage(File.open('YourFilename.extension', 'r'))
# or you can specify only absolute path to file
storage = crowdin.add_storage('YourFilename.extension')
# Download file
file = crowdin.download_file(your_file_id, your_destination, your_project_id)
# your_destination - filename or absolute path to the file, optional
# Without a destination option, the file will not be saved automatically
# project_id is optional, as it can be initialized with a Crowdin Client
# File revisions
# with initialized project_id in your Client
file_revisions = crowdin.list_file_revisions(your_file_id, limit: 10)
# or you can specify your project_id
file_revisions = crowdin.list_file_revisions(your_file_id, { limit: 10 }, your_project_id)
# Note: more examples you can find in spec folder
```
### Fetch all records
There is a possibility to fetch all records from paginatable methods using `fetch_all` method.
```ruby
# FetchAll options:
# * limit, Integer, default: 500 | How many records need to load per one request
# * offset, Integer, default: 0
# * request_delay, Integer (seconds), default: 0 | Delay between requests. To specify a delay in milliseconds use float values like 0.100
# Examples:
@crowdin.fetch_all(:list_projects)
# with options
@crowdin.fetch_all(:list_projects, { limit: 10, request_delay: 1 })
# playing with response per fetch
# Note: the block actually don't make any effect to finite result
@crowdin.fetch_all(:list_projects, { limit: 10, request_delay: 1 }) { |response| puts response['data'] }
# also, you could specify a retry configuration to handle some exceptions
# fetch all execution will be terminated if response status code is the same as one of the error_messages array value
# otherwise, the request will be retried so many times, as indicated at retries_count
@crowdin.fetch_all(:list_projects, {}, { request_delay: 2, retries_count: 3, error_messages: ['401'] })
```
### Command-Line Client
The Crowdin Ruby client support crowdin-console, where you can test endpoints easier
```console
$ bundle exec crowdin-console --enable-logger --api-token API_TOKEN --project-id PROJECT_ID
```
Or Crowdin Enterprise
```console
$ bundle exec crowdin-console --enable-logger --enterprise --api-token API_TOKEN --organization-domain DOMAIN --project-id PROJECT_ID
```
Note: you can specify full organization domain by adding '.com'
When execute you'll have IRB console with configured *@crowdin* instance
```
> @crowdin.list_projects
```
## Seeking Assistance
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.
## Contributing
If you would like to contribute please read the [Contributing](/CONTRIBUTING.md) guidelines.
## License
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.
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.