Class: Xliff::File

Inherits:
Object
  • Object
show all
Defined in:
lib/xliff/file.rb

Overview

Models a single file for translation

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(original:, source_language:, target_language:, datatype: 'plaintext') ⇒ File

Create a blank File object

Most often used to build an XLIFF file by hand.

Parameters:

  • original (String) —

    The original file name.

  • source_language (String) —

    The locale code for the source language.

  • target_language (String) —

    The locale code for the translated language.

  • datatype (String) (defaults to: 'plaintext') —

    The type of data represented.



45
46
47
48
49
50
51
52
53
 
# File 'lib/xliff/file.rb', line 45

def initialize(original:, source_language:, target_language:, datatype: 'plaintext')
  @original = original
  @source_language = source_language
  @target_language = target_language
  @datatype = datatype

  @headers = []
  @entries = []
end

Instance Attribute Details

#datatype ⇒ String (readonly)

The type of data represented

There are a variety of programming languages that can be represented by the XLIFF spec. Defaults to ‘plaintext`.

Returns:

  • (String) 


35
36
37
 
# File 'lib/xliff/file.rb', line 35

def datatype
  @datatype
end

#entries ⇒ Array<Header> (readonly)

The file’s translation entries

Returns:



12
13
14
 
# File 'lib/xliff/file.rb', line 12

def entries
  @entries
end

#headers ⇒ Array<Header> (readonly)

The file’s headers

Returns:



8
9
10
 
# File 'lib/xliff/file.rb', line 8

def headers
  @headers
end

#original ⇒ String (readonly)

The file’s name in the original project (used for reference when translating)

Returns:

  • (String) 


16
17
18
 
# File 'lib/xliff/file.rb', line 16

def original
  @original
end

#source_language ⇒ String (readonly)

The locale code for the source language

Returns:

  • (String) 


21
22
23
 
# File 'lib/xliff/file.rb', line 21

def source_language
  @source_language
end

#target_language ⇒ String (readonly)

The locale code for the translated language

This usually matches the ‘source_language` for files to be translated – it will differ if the file has been translated.

Returns:

  • (String) 


29
30
31
 
# File 'lib/xliff/file.rb', line 29

def target_language
  @target_language
end

Class Method Details

.from_xml(xml) ⇒ File

Decode the given XML into an Xliff::File object, if possible

Raises for invalid input, and parses all child translation entries.

Parameters:

Returns:



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/xliff/file.rb', line 117

def self.from_xml(xml)
  validate_source_xml(xml)

  file = File.new(
    original: xml['original'],
    source_language: xml['source-language'],
    target_language: xml['target-language'],
    datatype: xml['datatype'] || nil
  )

  import_file_header(xml, file)
  import_file_body(xml, file)

  file
end

.validate_source_xml(xml) ⇒ void

This method returns an undefined value.

Run a series of validations against the input XML

Automatically run prior to attempting to parse using ‘from_xml`.

Raises:

  • (ExceptionClass) —

    Raises exceptions if the input XML does not match expectations.



139
140
141
142
143
 
# File 'lib/xliff/file.rb', line 139

def self.validate_source_xml(xml)
  raise 'File XML is nil' if xml.nil?
  raise "Invalid File XML – must be a nokogiri object, got `#{xml.class}`" unless xml.is_a? Nokogiri::XML::Element
  raise 'Invalid File XML – the root node must be `<file>`' if xml.name != 'file'
end

Instance Method Details

#add_entry(entry) ⇒ void

This method returns an undefined value.

Add a translation entry to the file

Parameters:



69
70
71
72
73
 
# File 'lib/xliff/file.rb', line 69

def add_entry(entry)
  raise unless entry.is_a? Xliff::Entry

  @entries << entry
end

#add_header(header) ⇒ void

This method returns an undefined value.

Add arbitrary header data to the file

Parameters:



59
60
61
62
63
 
# File 'lib/xliff/file.rb', line 59

def add_header(header)
  raise unless header.is_a? Xliff::Header

  @headers << header
end

#entry_with_id(id) ⇒ Xliff::Entry?

Find the first entry with a given ‘id`, if present

Parameters:

  • entry (String) —

    The ‘id` to search for.

Returns:



79
80
81
82
83
 
# File 'lib/xliff/file.rb', line 79

def entry_with_id(id)
  @entries.find do |entry|
    entry.id == id
  end
end

#to_s ⇒ String

Encode this Xliff::File object to an XML string

Returns:

  • (String) 


107
108
109
 
# File 'lib/xliff/file.rb', line 107

def to_s
  to_xml.to_xml
end

#to_xml ⇒ Nokogiri::XML.fragment

Encode this Xliff::File object as an XLIFF document fragment representing the Xliff::File

Also encodes any headers and translation strings as children of the ‘File` element.

Returns:



90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/xliff/file.rb', line 90

def to_xml
  fragment = Nokogiri::XML.fragment('')
  file_node = fragment.document.create_element('file')
  file_node['original'] = @original
  file_node['source-language'] = @source_language
  file_node['target-language'] = @target_language
  file_node['datatype'] = @datatype

  add_headers_to_file(fragment, file_node)
  add_entries_to_file(fragment, file_node)

  file_node
end