resources/files/details
Provides additional and detailed information for a file.
- Information for a subsequent preview or deliverable creation.
- Erroneous segments (with source/target document only)
URL
(POST) /resources/files/details
PARAMETERS
The parameters are a JSON object included in the request body:
scope | The scope object. Note that if you use a document set or global search scope, you will receive an "available" = false result. In fact these scopes do not support files. | Mandatory |
did | The document id. This must be a document within the scope. | Mandatory |
locale | Language of the file. | Mandatory |
folder | Folder ID of the file. If not specified the call refers to the source or target document corresponding to "did" and "locale". | Optional |
name | Name the file. If not specified the call refers to the source or target document corresponding to "did" and "locale". | Optional |
Applicable for source/target files only: | ||
segmentDetails | Boolean, default is false. If true the system scans the texts of the document for errors, missing translations and last change date. | Optional |
RESULTS
A JSON with these properties:
preview | An object with details about previewing the file. See next table. | object |
file | An object providing general information on the file: Does it exist physically? Date and size? | object |
segments | If the file is the source/target document and parameter segmentDetails is true, then this node is included. See table below. | object |
hl | Information on highlighting options available when constructing a translated file (look for highlighting). See table below. | object? |
Preview node
Properties are:
canPreview | Boolean. True if a web preview is possible. | bool |
Preview activation | ||
needActivate | Boolean. If "canPreview" is false then this property indicates if previewing can be activated. | bool |
canActivate | If the preview requires activation: Indicates if the user has the right to activate. If so, typically show URL to go to activation page. | bool |
Preview parameter options | ||
previewer | The code of the previewer component. You can disregard this property. | string |
domain | The file type (domain). You will pass this to the preview method. | string |
encoding | A JSON object with these properties: canEdit: Boolean. True if the user shall be able to optionally select an encoding. Only true with text based file formats. Properties if canEdit is true: value: Last encoding used for this document & locale. Null if none. valueOriginal: The encoding of the original/source file. options: If "canEdit" is true you will find the list of all selectable encodings with properties "v" (code) and "t" (title).
| object |
baseUrl | Used with html files only. Permits to inject a base URL into the preview for proper rendering of images, css, etc. canEdit: Boolean. True if the file is a web page. Properties if canEdit is true: value: A suggested base url or null if none suggested. The list of available encodings is included in the result of resources/files/get | object |
File node
Provides information on the file and whether it exists physically or not. Properties are:
canSet | Whether user can replace or delete the file. This depends on the user's access rights. Note that the source document can never be changed. | bool |
name | The name of the file | string |
exists | True if the file exists physically. A deliverable that was never saved to the project is an example when this boolean is false. | bool |
date | Date of file. Null if file does not exist. | datetime? |
size | Size of file in bytes. Null if the file does not exist. | long? |
encoding | The encoding if the document is a text file (xml, json...). For example "utf-8". In some cases this information may not be available. For binary formats such as Word or InDesign, the encoding is null. | string? |
Segments node
Only included if "segmentDetails" parameter was set to true. Provides information on the actual texts in the language.
For example you can compare "segments.lastchange" ad "file.date" to know if the physical file is outdated and needs to be rebuilt from the newer text changes.
total | Total segments. | int |
missing | Total number of untranslated segments (in the specified locale). Note: Does not count empty segments that were set to green status. | int |
error | Total number of segments in error status (in the specified locale) | int |
lastchange | Most recent change of a text. Can only be null if the document has 0 segments (cannot occur normally). | datetime? |
Highlighting (hl) node
Describes the colors used when highlighting is enabled when calling resources/files/new
This node is null if the document format does not support the highlighting features.
Properties are:
editors | An array of objects, each with:
| object[] |
errors | A string containing the format / color used for the highlighting. Can be shown to end users to clarify in what color errors will be shown. | string |
EXAMPLE
Here we get details for a target document with
{
"preview": {
"canPreview": true,
"needActivate": false,
"canActivate": false,
"previewer": "CodeMirror",
"domain": "PLAINTEXT",
"baseurl": {
"canEdit": false,
"value": null
},
"encoding": {
"canEdit": true,
"value": "utf-8",
"options": [
{
"v": "UTF-8",
"t": "UTF-8"
},
{
"v": "UTF-16",
"t": "UTF-16"
}
{
"v": "WINDOWS-1258",
"t": "WINDOWS-1258"
}
]
}
},
"file": {
"canSet": true,
"name": "html.txt",
"exists": true,
"date": "2017-02-05T22:57:24.7403048Z",
"size": 502
},
"segments": {
"total": 8,
"lastchange": "2017-02-06T07:08:46.422Z",
"missing": 0,
"errors": 0
},
"hl": null
}
EXAMPLE HIGHLIGHTING
Some formats (Microsoft Word) include options for highlighting errors etc. in color. In that case the hl node is filled in:
{
...
"hl": {
"editors": [{
"v": 7,
"f": "cyan"
},
{
"v": 6,
"f": "green"
},
{
"v": 9,
"f": "magenta"
},
{
"v": 2,
"f": "yellow"
},
{
"v": 3,
"f": "red"
},
{
"v": 5,
"f": "grey"
}],
"errors": "red"
}
...
}