User Documentation¶

Features¶

The various features, (administrative rights) deserve to be detailed, Here they are:

All features: every feature you see below the separator in the list will be added for the user. Note that this has a potential to cause problems: If, for example, you simultaneously set Advanced features and Manage segments, it results in an editing rights conflict. There are security implications you need to consider when giving your users rights, so use this feature with care.

XLIFF export/import: enables XLIFF export/import of segments for the user. Especially important for those users who will be coordinating the translation effort throughout the project.

Receive notification e-mails: Add user to the list of recipients of Discovery/Content Scan/Alarm, etc notifications.

Can invite others: designates the user as a Project Manager, able to invite others onto the project. Take care not to include other, conflicting roles, such as Customer, which could re-restrict access.

Advanced features: give the user the power to edit languages as well as any entry in the project, and editing most setting, up to, and including, the URL inclusion-exclusion rules. Segmentation, publishing and certain advanced settings remain beyond the reach of the user.

Manage segments: make the user a Customer, with the ability to manage (approve or exclude) pending source segments. The user will also require a workflow role and an assigned target language to access the Workbench to manage segments. WARNING! This right restricts the user to this role, other features will be disabled!

NOTE Features are predominantly important from a project management viewpoint. Workflow roles, on the other hand, are used to manage user interaction on the Workbench, based on expertise (whether a user is a translator, proofreader or client will decide what sets of segments are available to them for editing - see the documentation of the Workbench for details).

After a user redeems their invitation using the link they receive in an e-mail, their address and username will appear under the owner. Their features and workflow roles can be edited in the list.

You can invite as many participants to the translation project as you’d like. You can also enable e-mail notifications for any of them by checking the notification icon in the last column.

Project Roles¶

Based on the project features that are available for a user, the following project ropes are available:

• Owner: Every project has an owner with unlimited powers over the project: the owner may add or remove anyone on the project, edit any entry in any language, including adding new languages, any change any setting, including the advanced ones. There can only be one owner on a project, but owners may renounce ownership, designating another user and setting their own privileges.
• Backup Owners: same as project owners. They can change any setting and entry, add or remove users, and modify language settings.
• Project Managers: can invite others onto the project. Other features and roles can be added as well. Take care not to include other, conflicting roles (restrictions override rights)
• Advanced Project Managers: they can edit languages, as well as any entry in the project. They can change most setting, up to and including the URL inclusion-exclusion rules. They cannot change segmentation rules or publishing settings. A few Advanced settings are also beyond their reach.
• Linguists: have access to the Simplified Dashboard and Content menu. They are only allowed to edit segments in their designated language and workflow role. They can receive notification emails about project updates, and may be given the power to import/export XLIFF files.
• Contributors: default users, capable of editing any entry in their selected language and workflow role, but nothing else. They may receive notification emails and project update emails, but they may not edit their features, nor invite anyone else, nor access any of the advanced settings.
• Customer: This role intended for a representative of the customer who excercises oversight over content. This role is read-only, meaning despite the target language added to the user, they are unable to actually make edits. They can Approve or Exclude segments.

Cache Header Overrides¶

Loading a page in the browser usually involves multiple requests for resources on the original site and other domains. A page can use multiple static resources (such as images) that require no localization.

If an image is referenced by relative name, such as /logo.jp, the hand of the proxy is forced: it has to assume the domain to be the proxy domain. The access path of the resource will become fr.exmaple.com/logo.jp assuming a French translation of example.com. This is a page request over the proxy, and therefore costs money.

Another common issue that lead to this feature is that static resources often have suboptimal Cache Headers. This leads to the same, unchanging content being served from the original server for each request individually, potentially decreasing the efficiency of the site and certainly adding to the number of requests that would have to go through the proxy. The Path Settings dialog can be used to override the default Cache Headers of resources of a given path or exact URL):

The screenshot above shows an override that will operate on all images that are located on the /res/img path and override their Cache Headers to the following default values:

cache override: public 
max-age: 86400
cookie override: clear cookies

This way, the resources become publicly cache-able on various independent nodes on the network. Depending on the location of the caching node and the pathway of the request, the content will be served from caches instead of going through the proxy pipeline.

The result is a considerable lightening of server load, and a decrease in the number of page requests that go through the proxy.

Freeze¶

The following are important options for when translation has already begun in earnest on a batch of content. At this point, it is a good idea to freeze the page list and the segments - that is, prevent inadvertent addition of new text or pages to the list you are currently working on.

WARNING: These settings can be overriden via explicit user action: adding Pages via the blue icon in the page list, or running Scans with the appropriate settings in place.

As you based quote on a specific Discovery/Scan (in other words, a specific state of the site at a given time), it wouldn’t do to return a few days after winning the project only to find that the news section was expanded with two new items and you have 4500 new source words to deal with - indelibly added to the project, but not part of the original deal.

The following features are available:

Freeze pagelist: Prevent new pages from being added to the pagelist. If you turn this option on, you can use the various preview modes withouht having to worry about new content.

Handle unknown pages as externalized: Pages that are not already in the pagelist will be externalized, that is, not translated at all, the same as if the page was manually excluded. Be aware that on a live site, this may result in an SEO penalty (due to duplicate content being detected by the crawler)!

Freeze translation memory: No new translatable segments will be added to a project as long as this Freeze is turned on (automatically enables Page Freeze).

Group pages¶

Specify path rules to group pages into one entry, preventing new pages from being added, but not removing preexisting pages, and making the grouped pages share a single dictionary, necessitating translation of only one. The pages will be grouped according to the path rules specified in the textbox, one path per line.

This feature is not meant to and does not decrease the amount of pages a Discovery has to crawl, but it makes project maintenance easier, as it prevents your page lists from being overcrowded with repetitive URLs.

JavaScript translation¶

This field contains the capture group definitions used to extract attribute-value pairs from JavaScript files selected for translation/localization. After entering the capture parameters and re-crawling the site, the proxy will display the selected JavaScript files as translatable pages in the pagelist, from where they can be selected for translation in the List View like regular pages, and any values for the selected attributes will be made available as translatable entries, which are treated identical to regular entries.

Entering “html” (note that the switch is separated by a space!) after the path specification will result in the proxy applying its HTML parser to the match instead of a plaintext parser, stripping out HTML markup and only offering the actual content for translation (otherwise, should the match contain markup, the translator must take care not to alter it, or risk breaking the translated site).

If a field of the JSON being parsed contains further JSON data in a stringified form ("key": "{\\"key\\":{\\"key\\":\\"value value value\\"}}"), the path can be passed to a recursive JSON translator by appending “json” to the path, then extending the path on the next line by adding “.json.”.

XPath Translation¶

The proxy can translate XML (eXtensible Markup Language) files sent by the remote server, according to the XPath standard of specifying elements of the XML structure. Similar to JavaScript translation, entering the “html” switch will result in the HTML parser being applied, while no switch will parse the match as plaintext.

Mark multiple Resources as Translatable¶

Using URL prefixes (N.B. fully qualified URL prefixes, including protocol, host, and possibly path structures!), the Proxy can enforce dictionaries over multiple resources in a single rule. This is especially useful if the site under translation contains an API (especially CREST APIs) whose responses also require translation, and each endpoint is served on a different path; in this case, entering the root of the API here will automatically capture all responses from that path without having to individually mark them as translatable from the Resources menu.

Additional Remote Request Headers¶

If the remote server requires certain headers to be present to serve legal responses, it will not be crawlable by default, as the crawler will not supply these. Entering the required headers here will result in them being appended to every request sent by the proxy, including the crawler requests, letting you crawl the site as required.

Ignore Classes¶

If a certain class of elements are not ought to be translated, they can be entered here. Elements with these classes will be treated as if they had the <translate=no> attribute, and will be treated as translation-invariant.

Ignore IDs¶

Similar to the “Ignored classes” option, this allows the treating of specific elements as translation-invariant, this time through HTML IDs.

Process Custom HTML Attributes¶

Some Content Management Systems may employ non-standard HTML attributes on various elements to style the page or otherwise affect aspects of their operation. If some of these attributes contain translatable text, you can enter them into the “As text” field to instruct the proxy to extract them. If they contain URLs that need to be mapped to the translated domain, you can use the “As link” field to instruct the proxy to map those non-standard link elements as well.

On request, it is also possible to activate an HTML parser for certain attributes, should they contain HTML formatting in their values.

Tweaks¶

In this section, you’ll find checkboxes for settings that apply to very specific circumstances. For those special snowflakes and occassions. When in doubt, contact us!

• Retaining original DOCTYPEs: By default, the proxy generates an HTML5 standards-compliant file to send to the client. If, for some reason, this causes problems due to the site relying on HTML4 standards for operation, some of which may be deprecated by HTML5, enabling this option will cause the Proxy Application to retain the original DOCTYPE declaration of the source page.
• Determine document type by GET instead of HEAD: some servers may return different responses to the HEAD request we use to determine document type than the GET request used to download content. Enabling this option forces the proxy to use GET requests for all operations, getting the correct content type from the server (as far as server-side configurations will allow).
• Detect JavaScript content type: JavaScript may not be explicitly declared as such on the server, being sent to the client with misleading content types. This causes the proxy to mis-identify such streams and not offer operations reserved for JS files. Enabling this option will force a deep check on each file sent to the client, to determine if they are indeed JavaScript code, regardless of their declared content type.
• Download images through the proxy: this will instruct the Proxy Application to attempt to map all <img src> attributes to the proxied domain. This is especially useful if the images are served only after authentication.
• Attempt to place tags according to punctuation when using TM-based pre-translation: if using a TM-based pre-translation, the Proxy Application may encounter segments where it cannot replace the XLIFF tags automatically, due to overly large differences between the contexts (possibly because of a changed site). If this option is enabled, the translator will try to replace the XLIFF tags according to their positions relative to punctuation marks in the segment. If successful, the TM entry’s confidence score will be increased by 0.1.
• Translate excluded pages when viewing them in Preview mode (but still not in live serving mode): It may be necessary sometimes to view excluded pages as if they were translated, in order to assess their layout, without actually making them available on the live site. Enabling this option allows just that, by propagating translations to the excluded pages if viewed in Preview mode, but keeping them untranslated in Live serving mode.
• Translate javascript: attribute: The Proxy is capable of extracting and translating code from the onclick attribute of elements. This feature may be used when a site uses this attribute to store translatable content inlined into the attribute and requires this content to be translated. Currently we only process the onclick event’s contents, all other events in the javascript attribute will be ignored.
• Detect and handle JSON-in-string responses, like "{\\"ResponseCode\\":\\"BadRequest\\"}: string-escaped JSON-format responses can be handled by activating this tweak. If active, the proxy will first attempt to string-unescape the response before passing it to the JSON parser, in order to recreate its base form.
• Make content in <script type="text/html"></script> translatable as a whole (don’t try to parse it as HTML): Script blocks may contain template data requiring translation, which is often signified by the text/html content type (instead of the more usual application major type). In such cases, HTML parsing can be undesirable, and can be bypassed by activating this option.
• Send a canonical link http header pointing to the original page on externalized pages: the proxy can insert a Link header into externalized pages, in order to avoid the SEO penalty associated with duplicate content. This header will point to the original address, and have rel=Canonical added, to designate the relationship.

Manual Publishing¶

Manual Publishing is advanced project control feature that gives project owners the ability to withhold the translations from being published on the live page (but not the preview, as it will always display the latest translation available!) until further notice.

The feature can be activated from the Advanced Settings page. Once activated, it will affect all translations going forward, but already-existing ones will not be “un-published”.

Once active, a new item will appear in the Bulk Actions menu of the Workbench: “Publish”. Running this action will cause all selected segments to be synchronized with their displayed translations, and once the action finishes, the markers in the status bar on the right of the entries will change to reflect this. If the action encounters an error, the server will attempt to rectify this by publishing the entire entry, after confirmation from the user. If the error is not recoverable, it will list the segments in error.

Default segment state¶

By default, the proxy will add new segments during a crawl as “Approved”, making them available for translation immediately. However, if the user/client so desires, this behavior can be changed to adding new segments in one of the two other states, “Pending” or “Excluded”. If the default setting is changed, the project owner, backup owners, or users with the Customer Role can alter segment states.

“Pending” segments are those that are awaiting a decision on translation. They will not be included in exports unless the relevant option is selected at export-time, and they will not appear in the Workbench for translation unless filtered for specifically. Those users able to alter segment states may change the state of these segments either by approving them for translation or excluding them altogether.

“Excluded” segments are those that have been deemed as not requiring translation at all. Unless the relevant option is selected, they are not included in exports and will not appear for translation unless filtered for specifically. Excluding a segment is not final, however: those users able to alter segment states may approve them for translation, making them available again.

NOTE!¶

The TMs you manage on this screen and the Workbench are different from the Translation Memory that is billed: they are used for concordance lookups and automatic translation, and they are completely free to create and use.

On the other hand, the proxy TM associated with a project is a database in the cloud that holds translations of segments. When you reimport your XLIFF files or run auto-pretranslate, you are writing to this project TM, which is billed the first time around.

Auto pre-translate¶

Automatize pre-translation: you can set up the project to automatically execute a pre-translate process for any new content that is found - you can hook it up with your TMs, or any Machine Translation services you subscribed to.

Pre-translation of incoming content can be done without user intervention or oversight. If new content is encountered, and at least one source is configured, a user-configurable timer starts counting down. Content is collected while this timer is running, and once it reaches zero, translation begins from the configured sources.

Content that cannot be translated (if no matches of acceptable confidence level were found in the TM or if the MT-engine returned no translation) is packaged into a Work package that you can have sent as XLIFF files to external systems, such as XTM, XTRF, or your Dropbox account. There are links at the bottom of the dialog you can use to visit the settings screens where you can set up these accounts.

Discovery Screen¶

Ignore queries: Add any query parameters to this field, separated by commas, to ignore them during Discoveries.

By default, the following URLs will turn up in the Page List as two separate pages:

http://www.example.com/examplepage.html

http://www.example.com/examplepage.html?querystring_1=foo&querystring_2=bar

Query strings can influence the content that will be served, but it is also common for a page to be completely unchanged regardless of their presence or absence. In such cases, query parameters are somwehat bothersome: they cause the Discovery to revisit the same page multiple times, they overcrowd the page list with unnecessary entries and divert attention from the real page that holds the content to be translated. It is a good idea to trim the list and exclude these superfluous pages using this feature.

Group pages by ignoring query parameters: In the same vein, you can also group pages based on ignored query parameters by adding those query parameters to this field. Query parameters are bona fide part of the URL, and therefore may or may not induce changes on a case-by-case basis. For every changed query parameter, we create a new page record. If you are sure about a set of query parameters not inducing any changes in page content, you can use this function to prevent them from getting picked up.

Discovery cookies You may extract the cookies from a user session and pass them to a Discovery. This feature is most useful when you need to deal with login walls and content that is only revealed within the context of a user session.

Note that we cannot guarantee that the cookie extraction method works with all proprietary logins, as there are several solutions which can use additional security measures such as IP checking, or checking the User-Agent header. As all the requests from the proxy and the crawler come from the Google Cloud, it is necessary for the target site to not block them. The success of a Discovery via the use of session cookies is highly dependent on the implementation details of a site.

Discovery page limit: It is usually not a very good idea to unleash unlimited Discoveries right off the bat, not unless you have a 100% understanding of a site’s structure. Granted, Discoveries don’t really cost much, so you are in no danger of incurring any serious expenses. But a Discovery can take time - and the shorter the time span required to create a quote with high confidence levels, the better.

For this and other reasons, it is a good idea to start with a “feeler” Discovery and take it from there, adjusting query string settings, adding prefix-based exlusion rules for unnecessary subsections, fine-tuning the settings as needed - this way, you can safely shape the Discovery incrementally, until it visits only those pages that you deem necessary.

Discovery history: By running subsequent limited Discoveries using progressively refined settings, you will also get contextual clues about site state by checking the Discovery History. By clicking on the small view history link under the timestamp of the last Discovery, you can avail yourself of all the statistical information revealed by your previous Discoveries by using the “Show info” button in the opening dialog. You can also verify the status and end state (termination reason) of your Discovery processes here.

Referred domains Links pointing to a different domain than the project website address will be treated as external referred domains and listed here for your convenience. Note that specific instances of external links (such as links to streamed media) can be localized(replaced) over the proxy. See Content > External links for further details.

Discovery Dialog¶

Discovery limit Repeated from the main screen, you can limit the Discovery to a set amount of pages before exiting.

Add & process newly found pages any pages the Discovery process finds during a crawl will be added to the page list. Note that this is explicit action by the user, therefore the Page Freeze setting has no effect in this case.

Add & process newly found resources Instruct the Discovery to add newly found Resources, such as *.js files to the project. The proxy makes collecting Resources a trifle, and there is a plethora of in-depth methods to translate content embedded within them. But translation of Resourecs is also known to be one of the trickiest parts of website localization. Beware, and woe betide the unready!

Add & process newly found image resources By enabling this option, image content found on the site is added to the Resources screen, where you can add localized counterparts and instruct the proxy to serve those in place of the original.

There is often a great deal of image content on websites, so indexing all of them can take a very long time to finish; it is a good idea to turn this option off the first time around, and enable it only later, when it is clear that image localization is also going to play a part.

Skip content type check if already determined (to be added)

Limit crawl depth There is more than one way of limiting the scope of a Discovery. In scenarios where you have to Discover richly interlinked pages (a wiki, for example) you can use the crawl depth to limit how deep the Discovery should be allowed to follow links.

Ignore pages matching the following regular expression You can specify any regex to apply to all URLs and ignore the given page if there is a match. This is a user- and crawl-specific setting. As always, we recommend that you test your regular expressions on regex101.com before using them. In this case, you can export your page list from Discovery > Pages and use that list as a test string for your regex.

Limit number of simultaneous requests Control the number of requests a Discovery is allowed to send to the original site simultaneously. Use this function to prevent the Discovery from flooding a smaller server with requests.

Exclusion rules You can set Discovery-specific exclusion rules by selecting Use temporary exclusion rules from the menu and adding your prefixes to the field that opens - use the buttons on the right to choose whether the prefix entered is an inclusion or exclusion rule.

By default (“Use current exclusion rules”), a Discovery will use the exclusion rules that you’ve set up on the Pages list screen.

Build Source Cache Source Caches have to be built during Discovery or Content Extraction crawls. This checkbox becomes available after you have enabled Source Caches in Dashboard > Page Cache. A dropdown menu will also appear, where you can select which of the Source Caches you’d like to use for the current Discovery. Please see the Source Caches section of this manual for the details. The option to keep the current Source Cache intact (“Preserve & use existing source cache”) is also available - these to options override each other, you should turn the latter off when you’re building a Source Cache.

After clicking on the blue “Discover” button, the Discovery starts and you will be returned to the main Discovery screen, where you can follow the word count statistics and check the status of the currently running process.

Work package generation¶

Work package name You can name your work package any way you like. As a suggestion, it is recommended that you give it a name that accurately reflects its contents, so as to make project management using work packages easier. So, for example, if you generate a work package for Arabic as a target language on April 10th, 2016 for all new content, you would name it something like ar-SA-untranslatedContent-2016-04-10 and so on.

Source language The source language for the project is displayed in this field (settable from the Dashboard main screen).

Work package language You can add multiple target languages for the Generation Process, but remember that a separate Work Package will be created for each target language.

Timeline You can specify which Content Extraction cycle you’d like to see in the Work Package that is to be generated. Click on “change” and use the timeline window to specify the time period, and the generator will limit its attention to just that timeframe. Select any two timestamped buttons to define the start and end of the timeframe.

Filter pages You can use your current selection (set on the Pages list screen), or define specific selected pages (both paths and full URLS are allowed) or folders using path prefixes. When you use a predefined list of pages (selected pages) the additional option of including both the HTTP and HTTPS versions of pages will be displayed as a checkbox.

Options Miscellanious options you can use to fine-tune the properties of your Work Package.

Split your package at preset words to create easily manageable chunks to assign to translators. Disable it to put everything in one big file (Note, however, that Work packages will be automatically split at 30.000 words)

You can choose to create separate work packages for hidden elements, and set the Work package generation to automatically take care of exporting for you. As with the general import function, you may elect to export only those entries that have no translation yet.

If you configured XTM, XTRF or Dropbox to integrate with the proxy, you may instruct the software to automatically send the exported XLIFF files to either one of those services. Use the dropdown menu to make your choice (only available if the checkbox is checked).

Work package list¶

You will receive e-mail notification about your generated work packages and they will appear in the list. You can use the refresh button to get an up-to-date view of your work packages.

If you hover over a work package, a floating menu will appear to the right with two options: XLIFF export and Progress report generation.

Serving domain mode (de.example.com)¶

In the serving domain mode, Easyling will publish the translated site either on a subdomain of the original (the default behavior, such as de.example.com), or on a completely separate naked domain (such as example.com). In order to use this mode, you (or the client) will have to modify the DNS settings corresponding to the original domain - the three to five records (three for subdomains, five for new naked domains) that need to be inserted in your DNS settings are found below the two input fields, and will change as you enter the desired serving domain.

Subdirectory publishing (example.com/de)¶

The alternative to subdomain-based publishing is to publish the site to retain your own domain, and publish the site as a subdirectory of the existing domain, i.e. the translated pages will be available on separate paths under your own domain. However, due to the way the proxy operates, this will require a specifically configured nginx reverse proxy server to be prepared and placed in front of your own webserver.

An example configuration snippet is available on the publishing interface, but this should be treated as only a guideline, to be customized according to your specific setup!

There are a variety of options at your disposal when implementing subdirectory publishing on your domain. You may choose to use nginx, CloudFront or any similar solution to use as a reverse proxy.

Proxy Solutions¶

To spare you the expense and time of developing a custom language selector, we have prepared two default solutions you can use. Each of these require the minimum possible intervention on the original site for deployment. Note, however, that seamless visual integration of the selector requires some fiddling with the CSS rules. The following two types of language selectors are available: