Versions Compared

Old Version 7

changes.mady.by.user Stephan Böhmig

Saved on

compared with

New Version 8

changes.mady.by.user Stephan Böhmig

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

(GET) /api/it/configuration?token=&option=

 

PARAMETERS

Parameters are:

option

token

The session token obtained when connecting.

 

Mandatory number.

This is the "translation option" for which you request the configuration. The option is an index into the list of all available translation options.

If this is the first time you call the API simply pass 0, to get the first (default) option. The resulting JSON includes the list of all the available options.

If a user then selects, let's say the third option, you would call this method again with &option=2 (0 = first option, 1 = second, ...).

If you indicate an invalid option, the system will use 0 and not return an error!

 

RESULTS

An HTTP status of 200 indicates success. Other HTTP status values indicate an error.

The method returns a JSON object:

 

option

The option (0, 1, ...) for which this JSON contains the configuration.

options

A JSON array of all available options. There is always at least one option.

Example:

"options": ["Default", "Technical", "Marketing"]

The "option" is the zero-based index into this array.

Image Removed

localesSpecifies the available languages. See description further down.maxFileSizeMB

The maximum file size in megabytes for translation requests.

You should always prevent a user to submit any files exceeding this limit.

The API itself will also check the limit.

formatsSpecifies the supported file formats. See description further down.peEnabledBoolean. Specifies if user can request a human post editing (improvement) of a machine translation.peTermsUrl

RESULTS

An HTTP status of 200 indicates success. Other HTTP status values indicate an error.

The method returns a JSON object:

 

options

A JSON array of all available options. There is always at least one option.

Example:

Image Added

Each array element is itself a JSON object containing full details.

 

Each option is a JSON object with these properties:

you need to propose a choice to the user. Example:
  • "PO/POT files - Default"
  • "Microsoft Powerpoint - All text"
  • "Microsoft Powerpoint - All text except red"

As you can see, the ".pot" extension can be both a PO/POT file or a Powerpoint template file.

 

EXAMPLE

Note that we have shortened the following JSON code:

Code Block{ "option": 1, "options": [ "Default", "Medical", "Technical" ], "locales": { "all": [ { "v": "af",

 

option

The option (0, 1, ...) for which this JSON contains the configuration. It is the index of this object in the options array (see above).

nameThe title of the option. This should be displayed to the user.
localesSpecifies the available languages. See description further down.
maxFileSizeMB

The maximum file size in megabytes for translation requests.

You should always prevent a user to submit any files exceeding this limit.

The API itself will also check the limit.

formatsSpecifies the supported file formats. See description further down.
peEnabledBoolean. Specifies if user can request a human post editing (improvement) of a machine translation.
peTermsUrl

Used when submitting post edit requests.

If not null then this is the URL to view usage Terms & Conditions.

Before a user requests a post edit of a machine translated file, the user must be asked to navigate to this URL.

For example, in your user interface you would add a checkbox like:

   [ ] I have read and agree with the Terms & Conditions.

If the property is null then the user does not need to accept any terms and conditions.

peDeadlineMinLeadHours

Used when submitting post edit requests.

If the user selects a deadline it must be at least this number of hours into the future.

peDeadlineMandatory

Used when submitting post edit requests.

If not null then this is the URL to view usage Terms & Conditions.

Before a user requests a post edit of a machine translated file, the user must be asked to navigate to this URL.

For example, in your user interface you would add a checkbox like:

   [ ] I have read and agree with the Terms & Conditions.

If the property is null then the user does not need to accept any terms and conditions.

peDeadlineMinLeadHours

Used when submitting post edit requests.

If the user selects a deadline it must be at least this number of hours into the future.

peDeadlineMandatory

Used when submitting post edit requests.

If not null then the user must choose a deadline for the work. If null then the choice of a deadline is optional.

 

Locales node

The "locales" node contains these properties:

"all": [ { "v": "af"

the user must choose a deadline for the work. If null then the choice of a deadline is optional.

all

A JSON array with all language codes and print names. Use this information to display language names.

Example:

Code Block

 

Locales node

The "locales" node contains these properties:

all

A JSON array with all language codes and print names. Use this information to display language names.

Example:

Code Block
"all": [
      {
        "v": "af",
        "t": "Afrikaans"
      },
      {
        "v": "ar",
        "t": "Arabic"
      },
        "t": "Afrikaans"
      },
      {
        "v": "ar",
        "t": "Arabic"
      },
      ...
]
anytoany

Indicates how source and target language combinations are stored in this JSON.

  • true: There are two lists, one with all source languages and another one with all target languages. Any combination source/target can be selected by the user.
  • false: There is a single list of available source/target language couples. When the user selects a source language, the list of available target languages must be refreshed.

In both cases, the language selector would look the same:

Image Removed

src
trg 

Applies if "anytoany" is true.

Both "src" and "trg" are the supported source and target language codes, respectively. And the user can translate from any source into any target language.

Example:

Code Block
"src": [ "en", "fr", "es-ES", "fi" ],
"trg": [ "en", "fr", "de"]
srctrg

Applies if "anytoany" is false.

Example:

Code Block
"srctrg": [ { "s": "en", "t": "fr" }, { "s": "en", "t": "de" }, { "s": "de", "t": "en" } ]

Here the user can choose from two source languages: English (en) and German (de). English can be translated into French and German. German can be translated into English. No other combinations are permitted.

 

Formats node

The "formats" node is a JSON array. Each element describes one file format (Word, HTML..) that can be translated:

 

namePrint name of the format, such as "Adobe Indesign", "Web page", etc.
ext

An array of possible file extensions. Example:

Code Block
"ext": [ ".indd", ".idml" ]

This record refers to Adobe Indesign files.

foptions

A list of format options. When translating a specific file a user may be given a choice how this file shall be handled. For example, the administrator may propose multiple options like:

  • Translate all content
  • Translate all except red text
  • Translate all except headers and footers

There is always at least one option. With just one, no need to ask the user to make a choice.

Example with two options:

Code Block
"foptions": [ 
      { "foption": 332, "name": "Translate all" },
      { "foption": 405, "name": "Translate all except red text" }
]

The foption value must be included with translation requests.

 

REMARKS

Let us discuss how you use the file options.

Imagine the user wants to translate "sample.pot". You would proceed as follows:

  • Fetch the configuration and display a pick list for the translation options (if more than one). Preselect the pick list item with index option.
  • Populate the language pick lists from the configuratio JSON. It is nice to preselect the last user choice!
  • Look up all records in the formats array that support the ".pot" extension. Usually this will yield just one, but in rare cases a file format may be ambiguous!
  • Compile all foption/name items from the formats selection.
    • If there is more than one item, 
    ...
]
    anytoany

    Indicates how source and target language combinations are stored in this JSON.

    • true: There are two lists, one with all source languages and another one with all target languages. Any combination source/target can be selected by the user.
    • false: There is a single list of available source/target language couples. When the user selects a source language, the list of available target languages must be refreshed.

    In both cases, the language selector would look the same:

    Image Added

    src
    trg 

    Applies if "anytoany" is true.

    Both "src" and "trg" are the supported source and target language codes, respectively. And the user can translate from any source into any target language.

    Example:

    Code Block
    "src": [ "en", "fr", "es-ES", "fi" ],
"trg": [ "en", "fr", "de"]
    srctrg

    Applies if "anytoany" is false.

    Example:

    Code Block
    "srctrg": [ { "s": "en", "t": "fr" }, { "s": "en", "t": "de" }, { "s": "de", "t": "en" } ]

    Here the user can choose from two source languages: English (en) and German (de). English can be translated into French and German. German can be translated into English. No other combinations are permitted.

     

    Formats node

    The "formats" node is a JSON array. Each element describes one file format (Word, HTML..) that can be translated:

     

    namePrint name of the format, such as "Adobe Indesign", "Web page", etc.
    ext

    An array of possible file extensions. Example:

    Code Block
    "ext": [ ".indd", ".idml" ]

    This record refers to Adobe Indesign files.

    foptions

    A list of format options. When translating a specific file a user may be given a choice how this file shall be handled. For example, the administrator may propose multiple options like:

    • Translate all content
    • Translate all except red text
    • Translate all except headers and footers

    There is always at least one option. With just one, no need to ask the user to make a choice.

    Example with two options:

    Code Block
    "foptions": [ 
      { "foption": 332, "name": "Translate all" },
      { "foption": 405, "name": "Translate all except red text" }
]

    The foption value must be included with translation requests.

     

    REMARKS

    Let us discuss how you use the file options.

    Imagine the user wants to translate "sample.pot". You would proceed as follows:

    • Fetch the configuration and display a pick list for the translation options (if more than one). Preselect the pick list item with index option.
    • Populate the language pick lists from the configuratio JSON. It is nice to preselect the last user choice!
    • Look up all records in the formats array that support the ".pot" extension. Usually this will yield just one, but in rare cases a file format may be ambiguous!
    • Compile all foption/name items from the formats selection.
    • If there is more than one item, you need to propose a choice to the user. Example:

      • "PO/POT files - Default"
      • "Microsoft Powerpoint - All text"
      • "Microsoft Powerpoint - All text except red"

    As you can see, the ".pot" extension can be both a PO/POT file or a Powerpoint template file.

     

    EXAMPLE

    The example below contains a configuration with a single option:

    Code Block
    {
    "options": [
        {
            "option": 0,
            "name": "Fast translation",
            "locales": {
                "all": [
                    {
                        "v": "af",
                        "t": "Afrikaans"
                    },
                    {
                        "v": "ar",
                        "t": "Arabic"
                    },
                    {
                        "v": "be",
                        "t": "Belarusian"
                    }
                ],
                "anytoany": true,
                "src": [
                    "af",
                    "ar",
                    "be"
                ],
                "trg": [
                    "af",
                    "ar",
                    "be",
                    "bg",
                    "ca"
                ]
            },
            "maxFileSizeMB": 20,
            "formats": [
                {
                    "name": "Adobe Indesign",
                    "ext": [
                        ".indd",
                        ".idml"
                    ],
                    "foptions": [
                        {
                            "foption": 38,
                            "name": "Default"
                        }
                    ]
                },
                {
                    "name": "Adobe Photoshop",
                    "ext": [
                        ".psd"
                    ],
                    "foptions": [
                        {
                            "foption": 44,
                            "tname": "AfrikaansDefault"
      },          {        }
"v": "ar",         "t": "Arabic"       },  ]
    {         "v": "be",  },
      "t": "Belarusian"       },  {
    ....     ],     "anytoany": true,     "srcname": ["Microsoft Powerpoint",
      "af",       "ar",       "beext",: [
      ....     ],     "trg": [       "af.ppt",
      "ar",       "be",       "bg",       "ca.pot",
      ....     ]   },   "maxFileSizeMB": 20,   "formats": [     {".pps",
       "name": "Adobe Indesign",       "ext": [         ".inddpptx",
          ".idml"       ],       "foptions": [.pptm",
             {           "foption": 38,.potx",
               "name": "Default"        ".potm",
}       ]     },     {       "name.ppsx":,
 "Adobe Photoshop",       "ext": [         ".psd"     ".ppsm"
 ],       "foptions": [         {  ],
        "foption": 44,           "namefoptions": "Default"[
        }       ]     },     {
	
 "name": "Microsoft Powerpoint",       "ext": [         ".ppt",         ".potfoption": 33,
         ".pps",           ".pptx",        "name": ".pptm",Default"
           ".potx",         ".potm",    }
    ".ppsx",         ".ppsm"       ],
       "foptions": [        }
{           "foption": 33],
            "namepeTermsUrl": "Default"null,
         }   "peDeadlineMinLeadHours": 12,
  ]     }     ....
"peDeadlineMandatory": true
 ],   "peTermsUrl": null,   "peDeadlineMinLeadHours": 12,}
   "peDeadlineMandatory": true]
}