TextUnited Documentation

Project Initialization

This guide explains how to set up a project within the TextUnited system, from defining details to selecting target languages and assigning initial team members.

Suggest Edits

Project initialization is the critical first step in setting up a multilingual project within TextUnited. It involves configuring the foundational elements necessary for managing translations across multiple languages. This process lays the groundwork for all subsequent activities related to the project, including assigning translators, setting deadlines, and tracking progress.

Why Initialize a Multilingual Project?

Initializing a multilingual project with TextUnited provides several benefits:

  • Centralized Management: All project-related activities are managed in one place, simplifying workflow and boosting productivity.
  • Customization: Tailor the project setup to fit specific needs, including selecting target languages, defining translation instructions, and setting up notification rules.
  • Collaboration: Facilitate collaboration among team members, translators, and clients through integrated communication channels.
  • Automation: Automate repetitive tasks, such as task assignment and deadline reminders, to save time and reduce errors.

Prerequisites

Before beginning the API calls, ensure you have the following prerequisites:

  • API Credentials: If you're using Basic Authentication, get your Company ID and API Key. For Bearer JWT Authentication, you'll need your JWT Access Token. Refer to our guides on Obtaining Your API Key and Company ID and Obtaining JWT Token for details.
  • Understanding of API Basics: Familiarity with RESTful APIs, HTTP methods (GET, POST, PUT, DELETE), and JSON format.
  • Development Environment: A suitable development environment set up for making HTTP requests, such as Postman or cURL.

Step-by-Step Guide to Initializing a Multilingual Project

Step 1: Prepare Your Project Data

When preparing to initialize a multilingual project via the TextUnited API, there are several key pieces of information you need to gather and organize. This data forms the backbone of your project configuration and ensures that the API can correctly interpret your requirements and execute the project setup accordingly.

Target Languages

  • Definition: Specify the languages you wish to translate your content into. This is crucial for determining the directionality of the project and ensuring that the correct linguistic resources are allocated.
  • Why It Matters: Knowing the target languages upfront allows TextUnited to pre-select the most appropriate translators based on their expertise and availability in those languages.

Source Content

  • Type: This refers to the content that needs translation. It can be plain text or files (e.g., PDF, DOCX).
  • Why It Matters: Having the source content ready ensures that the project can commence immediately after initialization, without any delays waiting for content to be uploaded or prepared.

Specific Translation Instructions or Glossaries

  • Details: Include any special instructions for translators or glossaries that define specific terminology or phrases.
  • Why It Matters: Providing clear guidelines and definitions helps maintain consistency and accuracy in translations, especially for complex or industry-specific content.

Team Members Involved in the Project

  • Information Required: Alongside roles (e.g., TRANSLATOR, PROJECT_MANAGER), gather full names, email addresses (used as usernames), and phone numbers for each team member.
  • Why It Matters: Accurate contact information facilitates effective communication throughout the project lifecycle, ensuring timely updates and addressing any issues promptly.

Source Language ID or Code

  • Definition: Identify the language(s) of the original content using ISO 639-1 or ISO 639-2 codes.
  • Why It Matters: Specifying the source language code helps TextUnited to match the content with the correct translation services and linguists who specialize in that language.

Target Language ID or Code

  • Definition: Similar to the source, identify the target language(s) using ISO codes.
  • Why It Matters: This ensures that the project is set up with the right target languages, aligning with the intended audience and market.

Segments of the Content to Translate

  • Identification: Break down the content into manageable segments or units for translation.
  • Why It Matters: Segmenting content makes it easier to manage translations, track progress, and allocate resources efficiently. It also allows for more precise targeting of specific parts of the content that may require specialized attention.

ℹ️

Note

To get your ID and Code for your source language and target languages, TextUnited has a list of supported languages that can be obtained by calling the Get Supported Languages endpoint.

Step 2: Construct the API Request

Use the TextUnited API to create a new multilingual project. The endpoint for creating a project typically looks like this:

POST /segments/projects

🚧

Base URL

The base URL for this request is https://api.textunited.com..

The request body should include details about the project, formatted in JSON. Here's an example payload:

{
  "customId": "<your_custom_id>",
  "taskId": "<your_task_id>",
  "name": "<your_project_name>",
  "description": "<description_of_your_project>",
  "startDateUtc": "<start_date_in_UTC>",
  "endDateUtc": "<end_date_in_UTC>",
  "sourceLanguageCode": "<your_source_language_code>",
  "targetLanguages": [
    {
      "targetLanguageCode": "<your_target_language_code>",
      "managedProject": <true_or_false>,
      "serviceTranslation": <true_or_false>,
      "serviceProofreading": <true_or_false>,
      "serviceAutomaticTranslation": <true_or_false>,
      "state": "<status_of_project>",
      "team": [
        {
          "id": <user_id>,
          "name": "<first_and_last_name>",
          "username": "<your_email_address>",
          "phone": "<user_phone_number>",
          "isProjectManager": <true_or_false>,
          "isTranslator": <true_or_false>,
          "isProofreader": <true_or_false>,
          "isInCountryReviewer": <true_or_false>
        }
      ],
      "referenceNumber": "<monolingual_project_reference_number>",
      "customField1": "<custom_monolingual_project_information>",
      "customField2": "<custom_monolingual_project_information>",
      "additionalInfo": "<monolingual_project_additional_information>"
    },
    {
      "targetLanguageCode": "<your_target_language_code>",
      "managedProject": <true_or_false>,
      "serviceTranslation": <true_or_false>,
      "serviceProofreading": <true_or_false>,
      "serviceAutomaticTranslation": <true_or_false>,
      "state": "<status_of_project>",
      "team": [
        {
          "id": <user_id>,
          "name": "<first_and_last_name>",
          "username": "<your_email_address>",
          "phone": "<user phone number>",
          "isProjectManager": <true_or_false>,
          "isTranslator": <true_or_false>,
          "isProofreader": <true_or_false>,
          "isInCountryReviewer": <true_or_false>
        }
      ],
      "referenceNumber": "your_reference_number>",
      "customField1": "<custom_project_information>",
      "customField2": "<custom_project_information>",
      "additionalInfo": "<additional_information>"
    }
  ],
  "segments": [
    {
      "customId": "<your_segment_custom_Id>",
      "content": "<content_of_your_segment>",
      "notes": "<notes_for_your_segment>",
      "taskId": "<identifier_for_the_task>",
      "languageSpecificNotes": [
        {
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>",
          "languageId": <your_language_Id>
        },
        {
          "languageId": <your_language_Id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        }
      ]
    },
    {
        "customId": "<your_segment_custom_Id>",
        "content": "<content_of_your_segment>",
        "notes": "<notes_for_your_segment>",
        "taskId": "<identifier_for_the_task>",
        "languageSpecificNotes": [
        {
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>",
          "languageId": <your_language_Id>
        },
        {
          "languageId": <your_language_Id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        }
      ]
    },
    {
        "customId": "<your_segment_custom_Id>",
        "content": "<content_of_your_segment>",
        "notes": "<notes_for_your_segment>",
        "taskId": "<identifier_for_the_task>",
        "languageSpecificNotes": [
            {
                "languageCode": "<your_language_code>",
                "note": "<note_for_specific_language>",
                "languageId": <your_language_Id>
            },
            {
                "languageId": <your_language_code>,
                "languageCode": "<your_language_code>",
                "note": "<note_for_specific_language>"
            }
        ]
    }
  ],
  "referenceNumber": "<your_project_reference_number>",
  "customField1": "<custom_project_information>",
  "customField2": "<custom_project_information>"
}

❗️

Note

  • Replace all placeholders and field values with actual values relevant to your project.
  • You cannot create a project with a proofreader and no translator; otherwise, you will get a 500 Internal Server Error.

Step 3: Send the Request

Using your preferred tool or library, send the POST request to the TextUnited API endpoint with the prepared payload. Ensure you include your API credentials in the request headers for authentication as follows:

curl --request POST \
     --url https://api.textunited.com/segments/projects \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Replace "<your_api_token>" with your actual JWT Access token that can be obtained from calling the Obtain JWT endpoint.

ℹ️

Try out the Request

To test this endpoint directly on our documentation platform, refer to the API reference for the Create Multilingual Project endpoint.

Step 4: Handle the Response

Upon successful submission, the API will respond with a confirmation message and details about the newly created project, including a unique project ID. Store this ID for future reference and API calls related to this project.

Example Response:

{
  "id": <auto_generated_project_identifier>,
  "customId": "<your_custom_id>",
  "taskId": "<your_task_id>",
  "name": "<your_project_name>",
  "description": "<description_of_your_project>",
  "creationDateUtc": <creation_date>,
  "startDateUtc": "<start_date_in_UTC>",
  "endDateUtc": "<end_date_in_UTC>",
  "sourceLanguageId": <your_source_language_id>,
  "sourceLanguageCode": "<your_source_language_code>",
  "targetLanguages": [
    {
      "id": <translation_project_id>,
      "targetLanguageId": <your_target_language_id>,
      "targetLanguageCode": "<your_target_language_code>",
      "managedProject": <true_or_false>,
      "serviceTranslation": <true_or_false>,
      "serviceProofreading": <true_or_false>,
      "serviceAutomaticTranslation": <true_or_false>,
      "progress": <progress_status>,
      "flag": <flag>,
      "state": "<status_of_project>",
      "team": [
        {
          "id": <user_id>,
          "name": "<first_and_last_name>",
          "username": "<your_email_address>",
          "phone": "<user phone number>",
          "isProjectManager": <true_or_false>,
          "isTranslator": <true_or_false>,
          "isProofreader": <true_or_false>,
          "isInCountryReviewer": <true_or_false>,
          "translationRate": <translation_rate>,
          "translationProductivity": <translation_productivity>,
          "proofreadedBy": <proofreader>,
          "proofreadingRate": <proofreading_rate>,
          "proofreadingProductivity": <proofreading_productivity>
        }
      ],
      "referenceNumber": "<your_reference_number>",
      "customField1": "<custom_project_information>",
      "customField2": "<custom_project_information>",
      "additionalInfo": "<additional_information>"
    },
    {
          "id": <user_id>,
          "name": "<first_and_last_name>",
          "username": "<your_email_address>",
          "phone": "<user phone number>",
          "isProjectManager": <true_or_false>,
          "isTranslator": <true_or_false>,
          "isProofreader": <true_or_false>,
          "isInCountryReviewer": <true_or_false>,
          "translationRate": <translation_rate>,
          "translationProductivity": <translation_productivity>,
          "proofreadedBy": <proofreader>,
          "proofreadingRate": <proofreading_rate>,
          "proofreadingProductivity": <proofreading_productivity>
        }
      ],
      "referenceNumber": "<your_reference_number>",
      "customField1": "<custom_project_information>",
      "customField2": "<custom_project_information>",
      "additionalInfo": "<additional_information>"
    },
  ],
  "domain": <domain>,
  "segments": [
    {
      "id": <your_segment_id>,
      "customId": "<your_segment_custom_Id>",
      "content": "<content_of_your_segment>",
      "notes": "<notes_for_your_segment>",
      "taskId": "<identifier_for_the_task>",
      "languageSpecificNotes": [
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        },
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        }
      ]
    },
    {
      "id": <your_segment_id>,
      "customId": "<your_segment_custom_Id>",
      "content": "<content_of_your_segment>",
      "notes": "<notes_for_your_segment>",
      "taskId": "<identifier_for_the_task>",
      "languageSpecificNotes": [
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        },
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        }
      ]
    },
    {
       "id": <your_segment_id>,
      "customId": "<your_segment_custom_Id>",
      "content": "<content_of_your_segment>",
      "notes": "<notes_for_your_segment>",
      "taskId": "<identifier_for_the_task>",
      "languageSpecificNotes": [
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        },
        {
          "languageId": <your_language_id>,
          "languageCode": "<your_language_code>",
          "note": "<note_for_specific_language>"
        }
      ]
    }
  ],
  "referenceNumber": "<your_reference_number>",
  "customField1": "<custom_project_information>",
  "customField2": "<custom_project_information>"
}

Visual Confirmation: Project Creation in TextUnited

After successfully initializing a multilingual project via the API, you might expect to see the project reflected within the TextUnited Translation Software interface. While the API primarily deals with backend interactions, understanding how the project appears in the UI can offer valuable insight into the configuration options and features available.

Upon logging into TextUnited and navigating to the "Projects" section, you should see your newly created project listed there.

The newly created project on the TextUnitd portal

The newly created project on the TextUnitd portal

Clicking on the project will reveal detailed information about the project, including the target languages, source content, assigned team members, and any specific instructions provided during the initialization phase. This visual confirmation reinforces the impact of your API call and sets the stage for further actions within the software.

Details for the first monolingual project (English to German (Austria))

Details for the first monolingual project (English to German (Austria))

Comprehensive Parameter List for Project Initialization

Below is a detailed table outlining the parameters required for initializing a multilingual project with TextUnited's API. This table aims to clarify each parameter, ensuring you have a clear understanding of their role and the expected input.

Field NameData TypeRequired/OptionalDescription
customIdstringOptionalA unique identifier for the project, used to associate the project with external systems or databases.

This ID is set during the project initialization and remains consistent throughout the project lifecycle.
taskIdstringOptionalA unique identifier for a specific task within the project, provided by the user.

This ID is used to track and manage individual tasks, including their status, assigned users, and due dates.

Users must ensure uniqueness and consistency of this ID across the project.
namestringRequiredA mandatory field that specifies the name of the project.

This name should be descriptive and meaningful, as it will be used to identify the project within the TextUnited platform and potentially linked with external systems or databases.
descriptionstringOptionalAn optional field that allows for a detailed narrative or explanation of the project.

This can include objectives, target audience, or any specific requirements that may influence the translation process.
startDateUtcdateRequiredThe start date and time of the project in Coordinated Universal Time (UTC).

This field must represent the current date and time at the moment of project initiation.
endDateUtcdateRequiredSpecifies the final deadline for the completion of the project in Coordinated Universal Time (UTC).

This date marks the cutoff point after which no further work on the project is expected to be done.
sourceLanguageIdint64OptionalThe numeric identifier of the source language. This parameter is optional and can be omitted if the sourceLanguageCode is provided instead.
sourceLanguageCodestringOptionalThe ISO 639-1 code of the source language. This parameter is optional; if provided, it should match the language of the original content.
targetLanguagesArray of ObjectsRequiredAn array of objects, each specifying a target language for the translation.

Each object must include the ISO language code (e.g., "EN" for English, "FR" for French).

This parameter defines the languages into which the source content will be translated.
targetLanguageIdint64OptionalThe numeric identifier of the target language. This parameter is optional if the targetLanguageCode is provided.

It corresponds to the internal language code used by TextUnited to identify languages.

For example, the identifier for English (US) is 41.
targetLanguageCodestringOptionalSpecifies the language code for the target language in a standardized format (e.g., en-US).

This parameter is optional and should only be used if the targetLanguageId is not defined.

It allows for more precise specification of dialects or regional variations beyond what may be covered by the targetLanguageId.
managedProjectBooleanOptionalIndicates whether the project management will be handled by TextUnited or internally by the company.

Set to true if TextUnited should manage the project, including task distribution, progress tracking, and notifications.

Set to false if the company prefers to handle project management internally, possibly requiring manual intervention for task assignments and progress updates.
serviceTranslationBooleanOptionalSpecifies whether to request human translation services for the project.

Setting this to true indicates that human translation is desired, while false implies automatic translation or no translation action is requested.
serviceProofreadingBooleanOptionalSpecifies whether human proofreading services should be requested for the project.

Setting this to true indicates that proofreading is desired, while false indicates no proofreading is required.
serviceAutomaticTranslationBooleanOptionalSpecifies whether to automatically translate the project content upon creation.

Setting this to true enables automatic translation services, potentially saving time and effort by generating initial translations without manual intervention.
statestringOptionalSpecifies the initial status of the project.

Options include "InProgress" for projects ready to start immediately, or "InPreparation" for projects requiring manual setup or preparation before beginning.

The default value is "InProgress".
teamArray of ObjectsOptionalAn array detailing users and their roles within the project.

Each object in the array specifies a user's ID and role designation (e.g., Project Manager, Translator).

This parameter is optional and only required when manual translation is selected. For automatic translations, this parameter can be omitted.
idIntegerRequiredA unique integer value representing the user's identifier within the TextUnited system.

This ID is essential for assigning specific roles to users within project teams, enabling personalized access and permissions based on the user's responsibilities.
namestringRequiredCombined first and last names of the user, used to identify the user in the system.
usernamestringRequiredEmail address registered with the system, serving as the user's unique identifier.

This email address is used to authenticate the user and grant access to the project based on permissions and roles assigned to it.
phonestringOptionalUser's contact phone number, used for communication purposes related to the project.

This can include notifications, updates, or direct inquiries regarding the project's progress or requirements.
isProjectManagerBooleanOptionalIndicates whether the user has been assigned the Project Manager role for the project.

Set to true if the user is the project manager; otherwise, false.
isTranslatorBooleanOptionalIndicates whether the user is designated as a translator for the project.

When set to true, it assigns the user the role of a translator, granting them access to translation tasks and responsibilities within the project.
isProofreaderBooleanOptionalIndicates whether the user is designated as a proofreader for the project.

When set to true, the user is responsible for reviewing translations for accuracy and adherence to style guidelines.
isInCountryReviewerBooleanOptionalIndicates whether the user is designated as an In-Country Reviewer.

An In-Country Reviewer is responsible for reviewing content within the local cultural and linguistic context to ensure accuracy and appropriateness.

Setting this to true assigns the reviewer role to the user for the project.
referenceNumberstringOptionalA user-defined string that represents a custom value for the project, such as a project code or internal identifier.

This allows for easy association and identification of the project within the user's internal systems or workflows.
customField1stringOptionalStores additional information that uniquely identifies the project within an external system.

This field is useful for linking TextUnited projects with records in other platforms or databases, enhancing interoperability and data consistency.
customField2stringOptionalStores additional information that uniquely identifies the project within an external system.

This field is useful for linking TextUnited projects with records in other platforms or databases, enhancing interoperability and data consistency.
additionalInfostringOptionalFree-form text field for providing supplementary information about the project, such as urgency levels, special instructions, or contextual notes.

This can be used to convey important details that may affect the translation process or project timeline.
segmentsArray of ObjectsRequiredAn array containing objects that represent individual segments of content to be translated.

Each object must specify the segment's content and may include additional metadata such as the original language, file name, or any custom identifiers.
customIdstringOptionalA unique identifier for a segment within an external system, used to track and manage segments outside of TextUnited.

This ID is typically prefixed with a recognizable string to easily identify the origin or system of the segment.
contentstringRequiredThe plain text or HTML markup content of the segment to be translated.

This field contains the actual text or HTML that needs to be localized.
notesstringOptionalAdditional guidance or instructions for translators, such as specific style guidelines or important cultural considerations.

This field is optional and can be used to provide extra context or emphasis on certain aspects of the translation task.
taskIdstringOptionalA custom identifier for a specific task within the project, set during project creation or update.

This ID is used to uniquely identify and manage individual tasks, facilitating targeted actions and reporting.
languageSpecificNotesArray of ObjectsOptionalAn array of objects, each containing language-specific notes for a particular segment.

This allows for detailed instructions or annotations tailored to specific languages, enhancing the accuracy and cultural appropriateness of translations.
languageIdint64OptionalThe unique identifier for the target language, used to specify the language in which the project's content should be translated.

This optional parameter allows for precise targeting of specific languages, especially useful in projects involving many languages or when working with less commonly used language codes.
languageCodestringOptionalThe ISO 639-1 code of the target language for the segment.

This optional parameter allows specifying the language for individual segments, especially useful in projects involving multiple languages or when translating specific parts of the content into different languages.
notestringOptionalLanguage-specific instructions or annotations provided to translators for better context or guidance on translation.

This can include stylistic cues, cultural considerations, or specific terminology to use.
referenceNumberstringOptionalA unique reference number for the multilingual project, used for internal tracking or association with external systems.

This optional field allows for additional identification beyond the standard project ID, facilitating easier retrieval or cross-referencing of projects.
customField1stringOptionalAn optional field for entering additional information that uniquely identifies the project within an external system or database.

This can be useful for linking project data across different platforms or for storing metadata relevant to the project's context.
customField2stringOptionalAn optional field for storing additional information that uniquely identifies the project within an external system or database.

This can be used for cross-system referencing or for storing metadata relevant to the project's context outside of TextUnited.

Updated 1 day ago