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.net/page/api

Defined Under Namespace

Modules: Errors

Constant Summary collapse

VERSION = 
"0.2.2"

Class Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ API

Create a new API object using the given parameters.

Parameters:

  • api_key (String) —

    the authentication API key can be found on the project settings page

  • project_id (String) —

    the project identifier.

  • account_key (String) —

    the account API Key

  • base_url (String) —

    the url of the Crowdin API



37
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
 
# File 'lib/crowdin-api.rb', line 37

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) || 'http://api.crowdin.net'

  @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])

  @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)



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

def log
  @log
end

Instance Method Details

#add_directory(name) ⇒ Object

Add directory to Crowdin project.

Request

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



173
174
175
176
177
178
179
 
# File 'lib/crowdin-api/methods.rb', line 173

def add_directory(name)
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/add-directory",
    :query  => { :name => name },
  )
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 :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)

Request

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



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/crowdin-api/methods.rb', line 25

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{ |k, v| v.nil? }

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

  params.delete_if{ |k, v| v.to_s.empty? }

  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/add-file",
    :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, please contact us to obtain API key for your account.

Request

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



298
299
300
301
302
303
304
 
# File 'lib/crowdin-api/methods.rb', line 298

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

#delete_directory(name) ⇒ Object

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

Request

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



187
188
189
190
191
192
193
 
# File 'lib/crowdin-api/methods.rb', line 187

def delete_directory(name)
  request(
    :method => :post,
    :path   => "/api/project/#{@project_id}/delete-directory",
    :query  => { :name => name },
  )
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.net/api/project/project-identifier/delete-file?key=project-key



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

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.net/api/project/project-identifier/delete-project?key=project-key



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

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.net/api/project/project-identifier/download-glossary?key=project-key



216
217
218
219
220
221
222
 
# File 'lib/crowdin-api/methods.rb', line 216

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.net/api/project/project-identifier/download-tm?key=project-key



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

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.

Request

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



126
127
128
129
130
131
132
 
# File 'lib/crowdin-api/methods.rb', line 126

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

#edit_project(params = {}) ⇒ Object

Edit Crowdin project.

Request

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



312
313
314
315
316
317
318
 
# File 'lib/crowdin-api/methods.rb', line 312

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

#export_translations ⇒ 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.

Request

POST api.crowdin.net/api/project/project-identifier/export?key=project-key



244
245
246
247
248
249
 
# File 'lib/crowdin-api/methods.rb', line 244

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

#get_projects(login) ⇒ Object

Get Crowdin Project details.

Request

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



339
340
341
342
343
344
345
 
# File 'lib/crowdin-api/methods.rb', line 339

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.



110
111
112
 
# File 'lib/crowdin-api.rb', line 110

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

#log=(logger) ⇒ Object

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



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

def log= logger
  @log = logger
end

#project_info ⇒ Object

Get Crowdin Project details.

Request

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



284
285
286
287
288
289
 
# File 'lib/crowdin-api/methods.rb', line 284

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

#request(params, &block) ⇒ Object 



70
71
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
 
# File 'lib/crowdin-api.rb', line 70

def request(params, &block)
  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.args}") if log
  log.debug("body: #{@response.body}") 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)
    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.net/api/supported-languages



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

def supported_languages
  request(
    :method => :get,
    :path   => "/api/supported-languages",
  )
end

#translations_status ⇒ Object

Track your Crowdin project translation progress by language.

Request

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



271
272
273
274
275
276
 
# File 'lib/crowdin-api/methods.rb', line 271

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 :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)

Request

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



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/crowdin-api/methods.rb', line 61

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{ |k, v| v.nil? }

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

  params.delete_if{ |k, v| v.to_s.empty? }

  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.net/api/project/project-identifier/upload-glossary?key=project-key



140
141
142
143
144
145
146
147
148
149
 
# File 'lib/crowdin-api/methods.rb', line 140

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.net/api/project/project-identifier/upload-tm?key=project-key



157
158
159
160
161
162
163
164
165
 
# File 'lib/crowdin-api/methods.rb', line 157

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 :source

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

  • :source - path for uploaded file (required)

Optional:

  • :import_duplicates (default: false)

  • :import_eq_suggestions (default: false)

  • :auto_approve_imported (default: false)

Request

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



104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/crowdin-api/methods.rb', line 104

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