Class: Crowdin::API

Inherits:
Object
  • Object
show all
Defined in:
lib/crowdin-api/methods.rb,
lib/crowdin-api.rb,
lib/crowdin-api/errors.rb,
lib/crowdin-api/version.rb

Overview

A wrapper and interface to the Crowdin api. Please visit the Crowdin developers site for a full explaination of what each of the Crowdin api methods expect and perform.

crowdin.com/page/api

Defined Under Namespace

Modules: Errors

Constant Summary collapse

VERSION = 
"0.6.0"

Class Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ API

Create a new API object using the given parameters.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/crowdin-api.rb', line 38

def initialize(options = {})
  @api_key     = options.delete(:api_key)
  @project_id  = options.delete(:project_id)
  @account_key = options.delete(:account_key)
  @base_url    = options.delete(:base_url) || 'https://api.crowdin.com'

  @log = nil

  options = {
    :headers                => {},
    :params                 => {},
    :timeout                => nil,
    :key                    => @api_key,
    :'account-key'          => @account_key,
    :json                   => true
  }.merge(options)

  options[:headers] = {
    'Accept'                => 'application/json',
    'User-Agent'            => "crowdin-rb/#{Crowdin::API::VERSION}",
    'X-Ruby-Version'        => RUBY_VERSION,
    'X-Ruby-Platform'       => RUBY_PLATFORM
  }.merge(options[:headers])

  options[:params] = {
    :key                    => @api_key,
    :'account-key'          => @account_key,
    :json                   => true
  }.merge(options[:params])

  RestClient.proxy = ENV['http_proxy'] if ENV['http_proxy']
  @connection = RestClient::Resource.new(@base_url, options)
end

Class Attribute Details

.log ⇒ Object

Default logger for all Crowdin::API instances

Crowdin::API.log = Logger.new($stderr)



28
29
30
 
# File 'lib/crowdin-api.rb', line 28

def log
  @log
end

Instance Method Details

#add_directory(name, params = {}) ⇒ Object

Add directory to Crowdin project.

Parameters

name - directory name (with path if nested directory should be created). (required)

Optional:

  • :is_branch - create new branch. Valid values - 0, 1. Only when create root directory.

  • :branch - a branch name.

Request

POST api.crowdin.com/api/project/project-identifier/add-directory?key=project-key



201
202
203
204
205
206
207
208
209
 
# File 'lib/crowdin-api/methods.rb', line 201

def add_directory(name, params = {})
  params[:name] = name

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/add-directory",
    :query  => params,
  )
end

#add_file(files, params = {}) ⇒ Object

Add new file to Crowdin project.

Parameters

files - Array of files that should be added to Crowdin project. file is a Hash { :dest, :source, :title, :export_pattern }

  • :dest - file name with path in Crowdin project (required)

  • :source - path for uploaded file (required)

  • :title - title in Crowdin UI (optional)

  • :export_pattern - Resulted file name (optional)

Optional:

  • :branch - a branch name. If the branch is not exists Crowdin will be return an error:

    "error":{
  "code":8,
  "message":"File was not found"

    }

Request

POST api.crowdin.com/api/project/project-identifier/add-file?key=project-key



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/crowdin-api/methods.rb', line 33

def add_file(files, params = {})
  params[:files] = Hash[files.map { |f| [
    f[:dest]               || raise(ArgumentError, "'`:dest`' is required"),
    ::File.open(f[:source] || raise(ArgumentError, "'`:source` is required'"))
  ] }]

  params[:titles] = Hash[files.map { |f| [f[:dest], f[:title]] }]
  params[:titles].delete_if { |_, v| v.nil? }

  params[:export_patterns] = Hash[files.map { |f| [f[:dest], f[:export_pattern]] }]
  params[:export_patterns].delete_if { |_, v| v.nil? }

  params.delete_if { |_, v| v.respond_to?(:empty?) ? !!v.empty? : !v }

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/add-file",
    :query  => params,
  )
end

#change_directory(name, params = {}) ⇒ Object

Rename or change directory attributes.

Parameters

name - Full directory path that should be modified (e.g. /MainPage/AboutUs).

Optional:

  • :new_name - new directory name (not contain path, name only)

  • :title - new directory title to be displayed in Crowdin UI

  • :export_pattern - new directory export pattern

  • :branch - a branch name

Request

POST api.crowdin.com/api/project/project-identifier/change-directory?key=project-key



256
257
258
259
260
261
262
263
264
 
# File 'lib/crowdin-api/methods.rb', line 256

def change_directory(name, params = {})
  params[:name] = name

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/change-directory",
    :query  => params,
  )
end

#create_project(params = {}) ⇒ Object

Create new Crowdin project. Important: The API method requires Account API Key. This key can not be found on your profile pages.

Request

POST api.crowdin.com/api/account/create-project?account-key=account-key



401
402
403
404
405
406
407
 
# File 'lib/crowdin-api/methods.rb', line 401

def create_project(params = {})
  request(
    :method => :post,
    :path   => "/api/account/create-project",
    :query  => params,
  )
end

#delete_directory(name, params = {}) ⇒ Object

Delete Crowdin project directory. All nested files and directories will be deleted too.

Parameters

name - Directory path (or just name if the directory is in root) (required) :branch - a branch name (optional)

FIXME When you try to remove the branch directory Crowdin will be return an error:

"error":{
  "code":17,
  "message":"Specified directory was not found"
}

Request

POST api.crowdin.com/api/project/project-identifier/delete-directory?key=project-key



229
230
231
232
233
234
235
236
237
 
# File 'lib/crowdin-api/methods.rb', line 229

def delete_directory(name, params = {})
  params[:name] = name

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/delete-directory",
    :query  => params,
  )
end

#delete_file(file) ⇒ Object

Delete file from Crowdin project. All the translations will be lost without ability to restore them.

Request

POST api.crowdin.com/api/project/project-identifier/delete-file?key=project-key



273
274
275
276
277
278
279
 
# File 'lib/crowdin-api/methods.rb', line 273

def delete_file(file)
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/delete-file",
    :query  => { :file => file },
  )
end

#delete_project ⇒ Object

Delete Crowdin project with all translations.

Request

POST api.crowdin.com/api/project/project-identifier/delete-project?key=project-key



429
430
431
432
433
434
 
# File 'lib/crowdin-api/methods.rb', line 429

def delete_project
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/delete-project",
  )
end

#download_glossary(params = {}) ⇒ Object

Download Crowdin project glossaries as TBX file.

Request

GET api.crowdin.com/api/project/project-identifier/download-glossary?key=project-key



287
288
289
290
291
292
293
 
# File 'lib/crowdin-api/methods.rb', line 287

def download_glossary(params = {})
  request(
    :method => :get,
    :path   => "/api/project/#{@project_id}/download-glossary",
    :output => params[:output],
  )
end

#download_tm(params = {}) ⇒ Object

Download Crowdin project Translation Memory as TMX file.

Request

GET api.crowdin.com/api/project/project-identifier/download-tm?key=project-key



301
302
303
304
305
306
307
 
# File 'lib/crowdin-api/methods.rb', line 301

def download_tm(params = {})
  request(
    :method => :get,
    :path   => "/api/project/#{@project_id}/download-tm",
    :output => params[:output],
  )
end

#download_translation(language = 'all', params = {}) ⇒ Object

Download ZIP file with translations. You can choose the language of translation you need or download all of them at once.

Note: If you would like to download the most recent translations you may want to use export API method before downloading.

Optional:

  • :output - a name of ZIP file with translations

  • :branch - a branch name

Request

GET api.crowdin.com/api/project/project-identifier/download/package.zip?key=project-key



145
146
147
148
149
150
151
152
 
# File 'lib/crowdin-api/methods.rb', line 145

def download_translation(language = 'all', params = {})
  request(
    :method  => :get,
    :path    => "/api/project/#{@project_id}/download/#{language}.zip",
    :output  => params.delete(:output),
    :query   => params,
  )
end

#edit_project(params = {}) ⇒ Object

Edit Crowdin project.

Request

POST api.crowdin.com/api/project/project-identifier/edit-project?key=key



415
416
417
418
419
420
421
 
# File 'lib/crowdin-api/methods.rb', line 415

def edit_project(params = {})
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/edit-project",
    :query  => params,
  )
end

#export_file(file, language, params = {}) ⇒ Object

Export a single translated file from Crowdin.

Parameters

file - File name with path in Crowdin project. (required) language - Target language. (required)

Optional:

  • :branch - a branch name

Request

GET api.crowdin.com/api/project/project-identifier/export-file?key=project-key



323
324
325
326
327
328
329
330
331
332
 
# File 'lib/crowdin-api/methods.rb', line 323

def export_file(file, language, params = {})
  params[:file] = file
  params[:language] = language
  request(
    :method => :get,
    :path   => "/api/project/#{@project_id}/export-file",
    :output => params.delete(:output),
    :query  => params,
  )
end

#export_translations(params = {}) ⇒ Object

Build ZIP archive with the latest translations.

Please note that this method can be invoked only every 30 minutes. Also API call will be ignored if there were no any changes in project since last export.

Optional:

  • :branch - a branch name

Request

GET api.crowdin.com/api/project/project-identifier/export?key=project-key



346
347
348
349
350
351
352
 
# File 'lib/crowdin-api/methods.rb', line 346

def export_translations(params = {})
  request(
    :method => :get,
    :path   => "/api/project/#{@project_id}/export",
    :query  => params,
  )
end

#get_projects(login) ⇒ Object

Get Crowdin Project details. Important: The API method requires Account API Key. This key can not be found on your profile pages.

Request

GET api.crowdin.com/api/account/get-projects?account-key=account-key



443
444
445
446
447
448
449
 
# File 'lib/crowdin-api/methods.rb', line 443

def get_projects()
  request(
    :method => :get,
    :path   => "/api/account/get-projects",
    :query  => { :login =>  },
  )
end

#log ⇒ Object

The current logger. If no logger has been set Crowdin::API.log is used.



116
117
118
 
# File 'lib/crowdin-api.rb', line 116

def log
  @log || Crowdin::API.log
end

#log=(logger) ⇒ Object

Sets the logger used by this instance of Crowdin::API



122
123
124
 
# File 'lib/crowdin-api.rb', line 122

def log= logger
  @log = logger
end

#project_info ⇒ Object

Get Crowdin Project details.

Request

POST api.crowdin.com/api/project/project-identifier/info?key=project-key



387
388
389
390
391
392
 
# File 'lib/crowdin-api/methods.rb', line 387

def project_info
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/info",
  )
end

#request(params, &block) ⇒ Object 



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/crowdin-api.rb', line 72

def request(params, &block)
  # Returns a query hash with non nil values.
  params[:query].reject! { |_, value| value.nil? } if params[:query]

  case params[:method]
  when :post
    query = @connection.options.merge(params[:query] || {})
    @connection[params[:path]].post(query) { |response, _, _|
      @response = response
    }
  when :get
    query = @connection.options[:params].merge(params[:query] || {})
    @connection[params[:path]].get(:params => query) { |response, _, _|
      @response = response
    }
  end

  log.debug("args: #{@response.request.args}") if log

  if @response.headers[:content_disposition]
    filename = params[:output] || @response.headers[:content_disposition][/attachment; filename="(.+?)"/, 1]
    body = @response.body
    file = open(filename, 'wb')
    file.write(body)
    file.close
    return true
  else
    doc = JSON.load(@response.body)
    log.debug("body: #{doc}") if log

    if doc.kind_of?(Hash) && doc['success'] == false
      code    = doc['error']['code']
      message = doc['error']['message']
      error   = Crowdin::API::Errors::Error.new(code, message)
      raise(error)
    else
      return doc
    end
  end

end

#supported_languages ⇒ Object

Get supported languages list with Crowdin codes mapped to locale name and standarded codes.

Request

GET api.crowdin.com/api/project/project-identifier/supported-languages?key=project-key



361
362
363
364
365
366
 
# File 'lib/crowdin-api/methods.rb', line 361

def supported_languages
  request(
    :method => :get,
    :path   => "/api/project/#{@project_id}/supported-languages",
  )
end

#translations_status ⇒ Object

Track your Crowdin project translation progress by language.

Request

POST api.crowdin.com/api/project/project-identifier/status?key=project-key



374
375
376
377
378
379
 
# File 'lib/crowdin-api/methods.rb', line 374

def translations_status
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/status",
  )
end

#update_file(files, params = {}) ⇒ Object

Upload fresh version of your localization file to Crowdin.

Parameters

files - Array of files that should be updated in Crowdin project. file is a Hash { :dest, :source }

  • :dest - file name with path in Crowdin project (required)

  • :source - path for uploaded file (required)

  • :title - title in Crowdin UI (optional)

  • :export_pattern - Resulted file name (optional)

Optional:

  • :branch - a branch name

Request

POST api.crowdin.com/api/project/project-identifier/update-file?key=project-key



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/crowdin-api/methods.rb', line 72

def update_file(files, params = {})
  params[:files] = Hash[files.map { |f|
    dest = f[:dest] || raise(ArgumentError, "'`:dest` is required'")
    source = ::File.open(f[:source] || raise(ArgumentError, "'`:source` is required'"))
    source.define_singleton_method(:original_filename) do
      dest
    end
    [dest, source]
  }]

  params[:titles] = Hash[files.map { |f| [f[:dest], f[:title]] }]
  params[:titles].delete_if { |_, v| v.nil? }

  params[:export_patterns] = Hash[files.map { |f| [f[:dest], f[:export_pattern]] }]
  params[:export_patterns].delete_if { |_, v| v.nil? }

  params.delete_if { |_, v| v.respond_to?(:empty?) ? !!v.empty? : !v }

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/update-file",
    :query  => params,
  )
end

#upload_glossary(file) ⇒ Object

Upload your glossarries for Crowdin Project in TBX file format.

Request

POST api.crowdin.com/api/project/project-identifier/upload-glossary?key=project-key



160
161
162
163
164
165
166
167
168
169
 
# File 'lib/crowdin-api/methods.rb', line 160

def upload_glossary(file)
  # raise "#{path} file does not exist" unless ::File.exist?(path)
  file = ::File.open(file, 'rb')

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/upload-glossary",
    :query  => { :file => file },
  )
end

#upload_tm(file) ⇒ Object

Upload your Translation Memory for Crowdin Project in TMX file format.

Request

POST api.crowdin.com/api/project/project-identifier/upload-tm?key=project-key



177
178
179
180
181
182
183
184
185
 
# File 'lib/crowdin-api/methods.rb', line 177

def upload_tm(file)
  file = ::File.open(file, 'rb')

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/upload-tm",
    :query  => { :file => file },
  )
end

#upload_translation(files, language, params = {}) ⇒ Object

Upload existing translations to your Crowdin project.

Parameters

files - Array of files that should be added to Crowdin project. file is a Hash { :dest, :source }

* :dest - file name with path in Crowdin project (required)
* :source - path for uploaded file (required)

language - Target language. With a single call it’s possible to upload translations for several

files but only into one of the languages. (required)

Optional:

  • :import_duplicates (default: false)

  • :import_eq_suggestions (default: false)

  • :auto_approve_imported (default: false)

  • :branch - a branch name

Request

POST api.crowdin.com/api/project/project-identifier/upload-translation?key=project-key



118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/crowdin-api/methods.rb', line 118

def upload_translation(files, language, params = {})
  params[:files] = Hash[files.map { |f| [
    f[:dest]               || raise(ArgumentError, "`:dest` is required"),
    ::File.open(f[:source] || raise(ArgumentError, "`:source` is required"))
  ] }]

  params[:language] = language

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/upload-translation",
    :query  => params,
  )
end