Collaboration and Communication
This guide will walk you through how to add comments to segments within your projects using TextUnited's API.
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 several primary methods for adding comments to your projects using TextUnited's API:
- Adding Comments by Project ID
- Adding Comments by Custom ID
- Adding Comments to All Languages
- Adding Comments to Specific Languages
- Adding Comments by Segment ID
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 Project 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 Project ID
Step 1: Prepare the Request
Construct the URL for the API endpoint using your Project 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 Project 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 Project 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.
Adding Comments to All Languages (Custom Segment 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 to All Languages (Custom Segment 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/comments
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/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 {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.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>",
"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/comments \
--header 'Authorization: Bearer <your_api_token>' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
-d '{
"segmentCustomId": "<customId_of_your_segment>",
"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 to All Languages (Custom Segment 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 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>"
}
]
}
]
}
]
Adding Comments to Specific Language (Custom Segment ID and Language Code)
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 to Specific Language (Custom Segment ID and Language Code)
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/comments
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/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 {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/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 to Specific Language (Custom Segment ID and Language Code).
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 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>"
}
]
}
]
}
]
Adding Comments to Specific Language (Custom Segment ID and Language 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 to Specific Language (Custom Segment ID and Language 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/comments
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/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 {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.targetLanguageId
: Indicates the target language ID 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>",
"targetLanguageId": "<your_target_language_id>",
"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/comments \
--header 'Authorization: Bearer <your_api_token>' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
-d '{
"segmentCustomId": "<customId_of_your_segment>",
"targetLanguageId": "<your_target_language_id>",
"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 to Specific Language (Custom Segment ID and Language 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 following 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>"
}
]
}
]
}
]
Adding Comments by Segment 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 TextUnited project ID for which you want to add comments.
Step-by-Step Guide - Adding Comments by Segment ID
Step 1: Prepare the Request
Construct the URL for the API endpoint using your Project 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:
segmentId
: Specifies the ID of the segment to which the comment is being added.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:
{
"segmentId": "<id_of_your_segment>",
"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 '{
"segmentId": "<id_of_your_segment>",
"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 Segment 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 Project 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>"
}
]
}
]
}
]
Congratulations!
Now you have a comprehensive guide for all the methods of adding comments to segments. Each section is detailed, including the necessary prerequisites, steps for preparation, sending the request, and verifying the response.
Updated about 2 months ago