cognate

Cognate is a set of translation tools for Flash/Animate CC

Features

• [x] Creates text files from your Flash project, which you can send out for translations
• [x] Writes translated text back into your Flash project
• [x] Preserves formatting of text in your project
• [x] Translated text can be rearranged and those changes will be reflected in Flash
• [x] The format of the text files can be customized
• [x] Supports the .xfl file format
• [ ] Supports the .fla file format
• [x] Can be used as a library for your own scripts
• [ ] Can be used as a command-line tool
• [ ] Supports incremental translation

Installation

npm install flash-cognate
`

## Usage

Generating translations files a Flash project:
```js
var cognate = require('flash-cognate'),
	fs 		= require('fs');

// "segments" are a <div> and <span> representation of your text
var segments = cognate.getSegmentsForXflFileAtPath('~/Flash/project/main.xfl');

fs.writeFileSync('~/text/toBeTranslated.xml', segments.stringify());

Writing translations to a Flash project:

var cognate = require('flash-cognate'),
	fs 		= require('fs');

var translated = fs.readFileSync('~/text/translated.xml');
var segments = cognate.parse(translated);

cognate.writeSegmentsToXflFileAtPath('~/Flash/project_german/main.xfl');

Internals

Cognate is essentially a wrapper around the fantastic Cheerio library, with various utility functions. Cognate has a load method which mirrors Cheerio's, but the result has some extended functionality that helps to manipulate Flash's symbol files.

Let's say that mySymbol.xml has these contents, in part:

...
<DOMStaticText>
  <matrix>
    <Matrix tx="2" ty="2"/>
  </matrix>
  <textRuns>
    <DOMTextRun>
      <characters>apple </characters>
      <textAttrs>
        <DOMTextAttrs face="Times" fillColor="#FFFFFF"/>
      </textAttrs>
    </DOMTextRun>
    <DOMTextRun>
      <characters>banana</characters>
      <textAttrs>
        <DOMTextAttrs face="Tahoma" fillColor="#FFE953"/>
      </textAttrs>
    </DOMTextRun>
  </textRuns>
</DOMStaticText>
...

You can access them like so:

var cognate = require('flash-cognate'),
	fs 		= require('fs');

var symbolFile = fs.readFileSync('~/Flash/project/LIBRARY/mySymbol.xml');
var $ = cognate.load(symbolFile);

var result = $('textRuns').withCharacters('apple banana').segment().stringify();

That would produce the output:

<div id="apple banana"><span style="font-family: Times; color: #FFFFFF;">apple </span><span style="font-family: Tahoma; color: #FFE953;">banana</span></div>

You can then modify the output and then save it back into your file:

...
result = result.replace('banana', 'mango');
var newSegment = cognate.parse(result);
$('textRuns').withCharacters('apple banana').segment(newSegment);

Hooks

Every translator or translation system is different, so they're not all going to want <div> and <span> tags and so on. There are a number of different requirements for the format. To meet with this, the stringify() and parse() functions can be customized.

Here are Cognate's default ones:

stringify: function() {
	return this.root().xml();
}

parse: function(xmlContent) {
	var $ = exp.load(xmlContent); // exp is a reference to cognate
	return $;
}

Here is an example of stringify/parse functions that enclose the <div> contents in a CDATA tag during translations:

var cognate = require('flash-cognate');

cognate.stringify = function() {
	var $ = cognate.load('');
	this.each(function(idx, elem){
		var $elem = $(elem);
		var cdata = '<![CDATA[' + $elem.xml() + ']]>';
		$elem.html(cdata);
	});
	return this.root().xml();
}

cognate.parse = function(xmlContent) {
	var $ = cognate.load(xmlContent);
	$('div').each(function(idx, elem){
		var $elem = $(elem);
		var cdata = $elem.contents().filter(function(i, e){
			return e.type === 'cdata';
		});
		$elem.html(cdata.text());
	});
	return $;
}