View source for PXML

== Introduction ==

Resource files for software localization come in different standard format, such as JSON, .resx, .properties and so on. To simplify showing context in a TMS or in a CAT tool like Trados Studio, best is to send strings to be translated as PXML file, i.e. Preview XML. This is a Lingoport format. 

Main advantages:
* The URL for the context on InContext server is easily parsed
* Files like JSON without support for comments are not well suited to pass attributes such as context URLs
* The parsing on the TMS or CAT tool is for one file format, not for all the different resource file types, so one parser/filter configuration
* Other attributes coming from Command Center can also be associated

== Configuration ==

The prerequisites for sending context are the following:
* an InContext server configured 
* a TMS configuration pointing to the InContext server
* a Localyzer project configured with that TMS

In TMS configuration, check the "Convert to PXML" checkbox. 

Any file sent to the TMS will be converted to a PXML file format. 

== PXML File Naming Convention ==
Repository files converted to PXML can be of many standard resource file types, such as:
* JSON
* resx
* properties
* YML
* .strings
* xml (many schemas here)
* etc.

Also, some of the files to be translated may have the same name, but be placed in different directory. A typical case is 'en.json'.

For those reasons, in order to know which converted PXML corresponds to which repository files, the naming convention looks like:
* lrmjson_LID349823_message.pxml

where the prefix indicates the source file format (here json), an ID of the path in the repo (here 349823), and the file name root itself (here message).

== PXML File Format ==

The following sample PXML shows the different elements:

<pre>

<?xml version="1.0" encoding="utf-8"?>
<pxml>
<!-- System prompt is a concatenation of the translation connection system prompt and the project prompt in Localyzer -->
<system_prompt><![CDATA[As a software application translator, translate an application user interface text from English to French. Special considerations for UI: Brevity is crucial, Clarity over creativity, Consistency with UI patterns, Action-oriented language. Return only the translated text-no explanation. This is for a hardware store.]]></system_prompt>
<resources>
  <string translate="1" segmentID="1" minLength="" maxLength="">
    <lrm_incontext>https://olivier.lingoport.io/incontext-server/lookup?key=183163_254&amp;token=Vozsmt6xmKxw5qVQ3c8w921Hj9NEKX70</lrm_incontext>
    <llm_prompt></llm_prompt>
    <SID>paint.coat</SID>
    <value><![CDATA[Coat]]></value>
  </string>
  <string translate="1" segmentID="3" minLength="" maxLength="">
    <lrm_incontext>https://olivier.lingoport.io/incontext-server/lookup?key=183165_254&amp;token=Vozsmt6xmKxw5qVQ3c8w921Hj9NEKX70</lrm_incontext>
    <llm_prompt></llm_prompt>
    <SID>machine.washer</SID>
    <value><![CDATA[Washer]]></value>
  </string>
</resources>
</pxml>

</pre>

The PXML elements:

* '''<pxml>''': The root element for this schema
* '''<system_prompt>''': If any prompt was provided at the translation configuration and or the project level, those are concatenated as the system prompt
* '''<resources>''': Many <string/> resources are under this level.
* '''<string>''': the string element contains the items to translated with a number of associated attributes 
** '''SID''': the unique segment identifier for that string, in effect the key for that string value.
** ''translate'': Upcoming, for now always 1 meaning the value is to be translated. 0 means do not translate this string.
** '''segmentID''': a placeholder, for now a counter starting at 1 in the PXML file and incremented for each <string> element
** ''minLength'': Upcoming - a value for the minimum length of the string, for now an empty string. This optional attribute would be set in String Manager
** ''maxLength'': Upcoming - a value for the maximum length of the string, for now an empty string. This optional attribute would be set in String Manager
** '''lrm_incontext''': the URL to the context associated with that string
** '''llm_prompt''': Upcoming - a prompt to help translate the value. See: [[Prompting]]
** '''value''': the string to be translated.

Note: Texts use CDATA so special characters added by users will not be misconstrued.

== Context URL ==

The context URL looks like the following:
   https://poc.lingoport.io/incontext-server/lookup?key=1573_105&amp;amp;token=8JZGug2O004Q6q9Z00ruO5g04Lr8w7SD

* https://poc.lingoport.io/incontext-server/ is the URL of the InContext server. This server must be accessible to translators
* lookup: the method to retrieve the context
* key: the context identifier
* token: only those with the right token can view the context


'''Note''':

In the XML-based PXML file, the ampersand (&) character is escaped as &amp;amp; to comply with XML standards. This ensures the file remains valid and can be parsed by TMS and CAT tools.

However, when accessing the context URL directly in a web browser, you must replace &amp;amp; with a regular ampersand (&amp;). For example:
 
'''XML format''' (escaped for validity):
* https://poc.lingoport.io/incontext-server/lookup?key=1573_105&amp;amp;token=8JZGug2O004Q6q9Z00ruO5g04Lr8w7SD

'''Browser format''' (actual usable link):
* https://poc.lingoport.io/incontext-server/lookup?key=1573_105&amp;token=8JZGug2O004Q6q9Z00ruO5g04Lr8w7SD