Unreal Engine Data Source Synchronization Process

Data Source Creation

One Repository corresponds to one data source. Currently, repositories with existing content do not support changing the data source. For Unreal Engine (hereinafter referred to as UE) data sources, they need to be used in conjunction with UE Plugins, hereinafter referred to as UE Connector. When defining a UE data source, users (typically game producers or localization managers) create an Access Token in the Flow 2 system. One Access Token corresponds to one Repository, which is then distributed to UE users (generally developers). UE users need to configure the Flow 2 API URL and Access Token in the UE Connector, and then customize a user-defined Friendly Name for distinction. The UE Connector allows switching between multiple definitions.

Data Pushing

Data is pushed through HTTP API, with interfaces supporting single or batch pushing. The main push parameters include:

• Access Token
• Source Language
• List[FText]
  • Namespace
  • Key
  • Value
• Identifier (Optional)

Multiple pushes are allowed, and the storage order follows the push order. If Namespace, Key, and Value are all identical, the data will be ignored. If only the Value changes, it will be updated; otherwise, new data will be added. During pushing, if no Identifier is provided, a new Identifier will be returned. The Identifier will be a unique hash, and a human-readable friendly name in the format of "three-english-words" (e.g., "elegant-purple-whale") will be provided alongside it. If this Identifier is used in subsequent pushes, data will be appended based on this Identifier without returning a new one.

Statistics Return

When pushing data, statistics information will be returned, including the number of texts that are new, updated, or ignored.

Marking Completion

When pushing is complete, use the Identifier as a parameter to call the completion marking interface, indicating that this push is complete. After marking completion, if you try to push again using this Identifier, an error will be returned.

Status Query

After pushing is complete, use the Identifier and target language as parameters to call the status query interface to check the localization progress of this data set.

Data Pulling

Use the Identifier as a parameter, with the target language being optional, to call the data pull interface. This returns localized data for the specified target language or all target languages.

List Identifiers

Using Access Token as a parameter, call the list identifiers interface to return a list of all Identifiers and whether they have been marked as completed, with no pagination.

Current Translations by Namespaces

Using Access Token as a parameter, call the current translations by namespaces interface to return the latest localization data for the specified namespaces (multiple), with no pagination.

Flow Chart

Interface Design

API Prefix

All API calls use a unified prefix. The current system API prefix is /api-key-auth. In the following API documentation, /{API_PREFIX} will be used as a variable to represent this prefix.

1. Data Push Interface

Endpoint: /{API_PREFIX}/ue/push
Method: POST
Content-Type: application/json

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	Access token

Request Body Parameters:

Parameter	Type	Required	Description
identifier	String	No	Identifier for appending data
texts	Array	No	List of texts to be localized

texts Array Element Structure:

Parameter	Type	Required	Description
namespace	String	No	Text namespace
key	String	No	Text key name
value	String	No	Text content

Request Example:

// Request Headers
X-Apikey: your-access-token

// Request Body
{
  "identifier": "optional-previous-identifier",
  "texts": [
    {
      "namespace": "Game",
      "key": "DIALOG_WELCOME",
      "value": "Welcome to our game!"
    },
    {
      "namespace": "UI",
      "key": "BUTTON_START",
      "value": "Start Game"
    }
  ]
}

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/push" \
  -H "Content-Type: application/json" \
  -H "X-Apikey: your-access-token" \
  -d '{
    "identifier": "optional-previous-identifier",
    "texts": [
      {
        "namespace": "Game",
        "key": "DIALOG_WELCOME",
        "value": "Welcome to our game!"
      },
      {
        "namespace": "UI",
        "key": "BUTTON_START",
        "value": "Start Game"
      }
    ]
  }'

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
identifier	String	Unique identifier for this push
friendlyName	String	Human-readable name (e.g., "elegant-purple-whale")
statistics	Object	Push statistics information

statistics Structure:

Parameter	Type	Description
addedCount	Number	Number of added texts
updatedCount	Number	Number of updated texts
ignoredCount	Number	Number of ignored texts

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "friendlyName": "elegant-purple-whale",
    "statistics": {
      "addedCount": 1,
      "updatedCount": 1,
      "ignoredCount": 0
    }
  }
}

2. Completion Marking Interface

Endpoint: /{API_PREFIX}/ue/complete
Method: POST
Content-Type: application/json

Request Parameters:

Parameter	Type	Required	Description
identifier	String	No	Identifier
importType	String	No	Import type, possible values: "sync", "update". "sync" will delete existing data and import everything again, "update" will append data to the existing base

Request Example:

{
  "identifier": "a1b2c3d4e5f6g7h8i9j0",
  "importType": "sync"
}

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "importType": "sync"
  }'

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
identifier	String	Identifier
completedStatus	String	Completion status: completed or incomplete
completedTime	String	Completion time

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "completedStatus": "completed",
    "completedTime": "2023-11-20 14:30:45"
  }
}

3. Status Query Interface

Endpoint: /{API_PREFIX}/ue/status
Method: POST
Content-Type: application/json

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	Access token

Request Body Parameters:

Parameter	Type	Required	Description
identifier	String	No	Identifier
targetLanguage	String	No	Target language code, e.g., "zh-CN"

Request Example:

// Request Headers
X-Apikey: your-access-token

// Request Body
{
  "identifier": "a1b2c3d4e5f6g7h8i9j0",
  "targetLanguage": "zh-CN"
}

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/status" \
  -H "Content-Type: application/json" \
  -H "X-Apikey: your-access-token" \
  -d '{
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "targetLanguage": "zh-CN"
  }'

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
identifier	String	Identifier
languages	Array	Progress information for each language

languages Array Element Structure:

Parameter	Type	Description
code	String	Language code
progress	Number	Translation progress percentage (0-100)

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "languages": [
      {
        "code": "zh-CN",
        "progress": 80
      },
      {
        "code": "ja-JP",
        "progress": 20
      }
    ]
  }
}

4. Data Pull Interface

Endpoint: /{API_PREFIX}/ue/pull
Method: POST
Content-Type: application/json

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	Access token

Request Body Parameters:

Parameter	Type	Required	Description
identifier	String	No	Identifier
targetLanguage	String	No	Target language code, if not provided, returns all languages

Request Example:

// Request Headers
X-Apikey: your-access-token

// Request Body
{
  "identifier": "a1b2c3d4e5f6g7h8i9j0",
  "targetLanguage": "zh-CN"
}

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/pull" \
  -H "Content-Type: application/json" \
  -H "X-Apikey: your-access-token" \
  -d '{
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "targetLanguage": "zh-CN"
  }'

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
identifier	String	Identifier
data	Array	Translation data list

data Array Element Structure:

Parameter	Type	Description
namespace	String	Text namespace
key	String	Text key name
sourceValue	String	Source text content
translations	Array	Translation list

translations Array Element Structure:

Parameter	Type	Description
language	String	Language code
value	String	Translated text content

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "identifier": "a1b2c3d4e5f6g7h8i9j0",
    "data": [
      {
        "namespace": "Game",
        "key": "DIALOG_WELCOME",
        "sourceValue": "Welcome to our game!",
        "translations": [
          {
            "language": "zh-CN",
            "value": "欢迎来到我们的游戏！"
          }
        ]
      },
      {
        "namespace": "UI",
        "key": "BUTTON_START",
        "sourceValue": "Start Game",
        "translations": [
          {
            "language": "zh-CN",
            "value": "开始游戏"
          }
        ]
      }
    ]
  }
}

5. List Identifiers Interface

Endpoint: /{API_PREFIX}/ue/identifiers
Method: POST
Content-Type: application/x-www-form-urlencoded

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	API key

Request Example:

// Request Headers
X-Apikey: your-access-token

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/identifiers" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Apikey: your-access-token"

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
success	Boolean	Whether the request was successful
total	Number	Total number of identifiers
identifiers	Array	List of identifiers

identifiers Array Element Structure:

Parameter	Type	Description
identifier	String	Unique identifier
friendlyName	String	Human-readable name (e.g., "elegant-purple-whale")
isMarkAsCompleted	Boolean	Whether it has been marked as completed

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "success": true,
    "total": 42,
    "identifiers": [
      {
        "identifier": "a1b2c3d4e5f6g7h8i9j0",
        "friendlyName": "elegant-purple-whale",
        "isMarkAsCompleted": true
      },
      {
        "identifier": "k1l2m3n4o5p6q7r8s9t0",
        "friendlyName": "brave-orange-tiger",
        "isMarkAsCompleted": false
      }
    ]
  }
}

6. Current Translations by Namespaces Interface

Endpoint: /{API_PREFIX}/ue/current-translations
Method: POST
Content-Type: application/json

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	Access token

Request Body Parameters:

Parameter	Type	Required	Description
namespaces	Array	No	List of namespaces to retrieve translations for
targetLanguages	Array	No	List of target language codes, if not provided, returns all available languages

Request Example:

// Request Headers
X-Apikey: your-access-token

// Request Body
{
  "namespaces": ["Game", "UI"],
  "targetLanguages": ["zh-CN", "ja"]
}

curl Command Example:

curl -X POST "https://api.example.com/{API_PREFIX}/ue/current-translations" \
  -H "Content-Type: application/json" \
  -H "X-Apikey: your-access-token" \
  -d '{
    "namespaces": ["Game", "UI"],
    "targetLanguages": ["zh-CN", "ja"]
  }'

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Object	Return data

data Structure:

Parameter	Type	Description
data	Array	Current localized text data grouped by namespace

data Array Element Structure:

Parameter	Type	Description
namespace	String	Text namespace
strings	Array	List of strings in this namespace

strings Array Element Structure:

Parameter	Type	Description
key	String	Text key name
sourceValue	String	Source text content
translations	Array	Translation list
lastUpdated	String	Last update time

translations Array Element Structure:

Parameter	Type	Description
language	String	Language code
value	String	Translated value

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "data": [
      {
        "namespace": "Game",
        "strings": [
          {
            "key": "DIALOG_WELCOME",
            "sourceValue": "Welcome to our game!",
            "lastUpdated": "2023-11-20 14:30:45",
            "translations": [
              {
                "language": "zh-CN",
                "value": "欢迎来到我们的游戏！"
              },
              {
                "language": "ja",
                "value": "ゲームへようこそ！"
              }
            ]
          },
          {
            "key": "DIALOG_GOODBYE",
            "sourceValue": "Thanks for playing!",
            "lastUpdated": "2023-11-20 14:30:45",
            "translations": [
              {
                "language": "zh-CN",
                "value": "感谢您的游玩！"
              },
              {
                "language": "ja",
                "value": "プレイしていただきありがとうございます！"
              }
            ]
          }
        ]
      },
      {
        "namespace": "UI",
        "strings": [
          {
            "key": "BUTTON_START",
            "sourceValue": "Start Game",
            "lastUpdated": "2023-11-20 14:30:45",
            "translations": [
              {
                "language": "zh-CN",
                "value": "开始游戏"
              },
              {
                "language": "ja",
                "value": "ゲームを始める"
              }
            ]
          }
        ]
      }
    ]
  }
}

7. Target Languages List Interface

Endpoint: /{API_PREFIX}/ue/target-languages
Method: GET
Content-Type: application/json

Request Headers:

Parameter	Type	Required	Description
X-Apikey	String	Yes	API key

Request Example:

// Request Headers
X-Apikey: your-access-token

curl Command Example:

curl -X GET "https://api.example.com/{API_PREFIX}/ue/target-languages" \
  -H "X-Apikey: your-access-token"

Response Parameters:

Parameter	Type	Description
code	Number	Status code
msg	String	Status message
data	Array	List of available target languages

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": [
    "zh-CN",
    "en-US"
  ]
}

Error Response

When a request fails, all interfaces return a unified error format:

Error Response Parameters:

Parameter	Type	Description
success	Boolean	Fixed as false
errorCode	String	Error code
errorMessage	String	Error description

Error Response Example:

{
  "success": false,
  "errorCode": "invalid_token",
  "errorMessage": "The provided access token is invalid or expired"
}

Common Error Codes:

Error Code	Description
invalid_token	Access token is invalid or expired
invalid_identifier	Identifier is invalid
identifier_completed	Identifier has been marked as complete, cannot add more data
empty_data	No text data provided
server_error	Server internal error