Collaboration and Communication

Collaboration and communication are foundational elements in the successful execution of multilingual projects. Comments within your projects serve as a bridge between team members, facilitating discussions, clarifications, and improvements. TextUnited provides this tool for direct communication on specific text segments. We'll cover two methods for adding comments: using either the TextUnited project ID or a custom project ID.

Why Add Comments to Your Multilingual Projects?

Comments are not just about leaving notes; they are a dynamic way to engage with your project's content and team. Here's why incorporating comments into your project workflow is beneficial:

• Clarity and Understanding: Comments provide a platform for team members to share insights, ask questions, and offer corrections, leading to clearer and more accurate translations.
• Efficient Communication: Instead of relying on emails or external messaging platforms, comments keep all project-related conversations contained within the project itself, enhancing efficiency.
• Continuous Improvement: Comments encourage a culture of continuous improvement by highlighting areas for enhancement, whether it's the quality of the translation or the clarity of the instructions.
• Team Engagement: Engaging with comments shows active participation and interest in the project's success, boosting morale and productivity among team members.

What You Will Learn

This guide will cover two primary methods for adding comments to your projects using TextUnited's API:

• Adding Comments by TextUnited ID: Utilize the unique project identifier provided by TextUnited to add comments directly to segments within your project.
• Adding Comments by Custom ID: Use a custom identifier for your project to facilitate easy navigation and efficient comment addition.

Each section will provide a step-by-step guide, including detailed explanations of the API endpoints, necessary request parameters, and expected responses. Additionally, we'll showcase how to verify the addition of comments within the TextUnited Translation Software interface, enhancing your understanding of the entire process.

Adding Comments by TextUnited ID

This guide will take you through the process of adding comments to segments within your projects using TextUnited's API, specifically targeting projects identified by their TextUnited project ID.

Prerequisites

Ensure you have:

• 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.
• The TextUnited project ID for which you want to add comments.

Step-by-Step Guide - Adding Comments by TextUnited ID

Step 1: Prepare the Request

Construct the URL for the API endpoint using your project's TextUnited ID. The endpoint format is as follows:

POST /segments/projects/{textunited-project-id}/segments/comments

Replace {textunited-project-id} with your actual project ID.

📘

Get your TextUnited Project ID

To get your TextUnited project ID, call this endpoint "Get Projects" and, from the responses, locate the "id" field that is automatically generated by TextUnited. For a more detailed guide, follow this guide to extract your project ID.

Step 2: Set Headers

Include your API credentials in the request headers for authentication. Typically, this involves setting the Authorization header with your API key. Here's an example using cURL:

curl --request POST \
     --url https://api.textunited.com/segments/projects/{textunited-project-id}/segments/comments \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json'

Replace "<your_api_token>" with your actual JWT Access token that can be obtained from calling the Obtain JWT endpoint. Replace {textunited-project-id} with your TextUnited project ID.

Step 3: Prepare the Request Body

The request body should contain the following fields:

• segmentCustomId: Specifies the custom ID of the segment to which the comment is being added.
• targetLanguageCode: Indicates the target language code of the project version where the segment resides.
• commentText: Contains the actual text of the comment being added to the segment.
• commentAuthor: Provides the name or nickname of the person who is adding the comment.

Here's an example:

{
  "segmentCustomId": "<customId_of_your_segment>",
  "targetLanguageCode": "<your_target_language_code>",
  "commentText": "<your_comment_text>",
  "commentAuthor": "<first_and_lastname_of_author"
}

Step 4: Send the Request

Using a tool or library of your choice, send a POST request to the constructed URL with the prepared request body. If you're using cURL, the command would look like this:

curl --request POST \
     --url https://api.textunited.com/segments/projects/{textunited-project-id}/segments/comments \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     -d '{
 				 "segmentCustomId": "<customId_of_your_segment>",
 				 "targetLanguageCode": "<your_target_language_code>",
				 "commentText": "<your_comment_text>",
 				 "commentAuthor": "<first_and_lastname_of_author"
			}'

👍

Success

Once the request runs successfully, you'll get a status code of 200 OK and the ID of the comment returned.

ℹ️

Try out your Request

To make your request and view your response directly on our documentation platform, you can refer to our API Reference on Add Comments by TextUnited ID.

Step 5: Verify the Response

Check the response from the server to confirm the comment was added successfully by calling the Get Segments by TextUnited ID endpoint. For a detailed guide on calling this endpoint, refer to this Project Detail guide. You will get the following response:

Example Response

[
    {
        "source": {
            "id": <identifier_of_the_segment>,
            "customId": "<custom_identifier_of_the_segment>",
            "content": "<content_of_the_segment>",
            "notes": "<note_for_the_segment>",
            "taskId": "<identifier_for_the_specific_task>",
            "languageSpecificNotes": "<specific_tasks_for_the_language>"
        },
        "translations": [
            {
                "id": <identifier_for_the_translator>,
                "languageId": <language_identifier>,
                "languageCode": "<language_code>",
                "content": "<translated_content>",
                "status": "<status_of_the_translation>",
                "comments": [
                    {
                        "id": <identifier_for_comment>,
                        "comment": "<name_of_the_comment_author: comment_text"
                    }
                ]
            }
        ]
    }
]

From the example response above, notice that the following comment has been added to the specific segment specified in the request, and that the "commentText" has been appended to the "commentAuthor"

 "comments": [
     {
       "id": <identifier_for_comment>,
       "comment": "<name_of_the_comment_author: comment_text"
     }
 ]

The id is automatically generated by TextUnited for the comment.

Adding Comments by Custom ID

This guide will guide you through the process of adding comments to segments within your projects using TextUnited's API, focusing on projects identified by their custom project ID.

Prerequisites

Ensure you have:

• Your TextUnited API credentials (Company ID and API Key). To obtain these credentials, please refer to our Guide on Obtaining Your API Key and Company ID.
• The custom project ID for which you want to add comments.

Step-by-Step Guide - Adding Comments by Custom ID

Step 1: Prepare the Request

Construct the URL for the API endpoint using your project's custom ID. The endpoint format is as follows:

POST /segments/projects/custom/{custom-project-id}/segments/comment

Replace {custom-project-id} with your actual custom project ID.

📘

Get your Custom Project ID

To get your custom project ID, call this endpoint "Get Projects" and, from the responses, locate the "customId" field that you set while creating a multilingual project on TextUnited.

Step 2: Set Headers

Include your API credentials in the request headers for authentication. Typically, this involves setting the Authorization header with your API key. Here's an example using cURL:

curl --request POST \
     --url https://api.textunited.com/segments/projects/custom/{custom-project-id}/segments/comment \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json'

Replace "<your_api_token>" with your actual JWT Access token that can be obtained from calling the Obtain JWT endpoint. Replace {custom-project-id} with your custom project ID.

Step 3: Prepare the Request Body

The request body should contain the following fields:

• segmentCustomId: Specifies the custom ID of the segment to which the comment is being added.
• targetLanguageCode: Indicates the target language code of the project version where the segment resides.
• commentText: Contains the actual text of the comment being added to the segment.
• commentAuthor: Provides the name or nickname of the person who is adding the comment.

Here's an example:

{
  "segmentCustomId": "<customId_of_your_segment>",
  "targetLanguageCode": "<your_target_language_code>",
  "commentText": "<your_comment_text>",
  "commentAuthor": "<first_and_lastname_of_author"
}

Step 4: Send the Request

Using a tool or library of your choice, send a POST request to the constructed URL with the prepared request body. If you're using cURL, the command would look like this:

curl --request POST \
     --url https://api.textunited.com/segments/projects/custom/{custom-project-id}/segments/comment \
     --header 'Authorization: Bearer <your_api_token>' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     -d '{
 				 "segmentCustomId": "<customId_of_your_segment>",
				 "targetLanguageCode": "<your_target_language_code>",
 				 "commentText": "<your_comment_text>",
 				 "commentAuthor": "<first_and_lastname_of_author"
}'

👍

Success

Once the request runs successfully, you'll get a status code of 200 OK and the ID of the comment returned.

ℹ️

Try out your Request

To make your request and view your response directly on our documentation platform, you can refer to our API Reference on Add Comments by Custom ID.

Step 5: Verify the Response

Check the response from the server to confirm the comment was added successfully by calling the Get Segments by Custom ID endpoint. For a detailed guide on calling this endpoint, refer to this Project Detail guide. You will get the same response used in this example above.