Sample Scripts

Note: this is as of LTK version 1.3.5

Key

red text = this is an example of what might be shown, but the actual values may be different for you

bold blue text = these are ltk commands

blue text = these are user inputs to prompts.  Your inputs may be different

green text = these are file and directory paths

bold text = this is terminology that is being defined

Setting Up Your Project

You need to set up an ltk project before you can send any content to Enterprise for translation.  An ltk project consists of 1.) a set of configurations for the filesystem connector, and 2.) local tracking of documents that the project is managing.  Local tracking allows users to only add documents to the project that they want the project to manage.  The documents in local tracking should match up with the documents in the Enterprise project connected to the ltk project (see the example "ltk init" procedure below), but this is not guaranteed as uploads may fail or the Enterprise project can be modified from other sources without the ltk project knowing about it.  There are commands that can bring the ltk project back into sync with the Enterprise project, but those aren't in the scope of these basic examples and will just be explained briefly at the end.  The command for setting up an ltk project is ltk init.  This will take you through a wizard to configure the project. In this example, we are going to create an ltk project in the directory ~/myproject.  This makes ~/myproject the root of the project.  You must be in the root of the project or in a subdirectory of the root for the filesystem connector to work.  The following is an example of what using ltk init would look like:

cd ~/myproject //we are going to use "~/myproject" as the project root
ltk init

The init wizard will have the following sections:
---------------------------
SELECT Enterprise COMMUNITY
---------------------------
  ID Name               UUID
---- ------------------ ------------------------------------
   0 My Community       01234567-89ab-cdef-0123-456789abcdef
   1 My Other Community abcdef98-7654-3210-abcd-ef9876543210
Select Enterprise Community ID: 0

Enter the ID of the Enterprise Community you want to connect to.  In this example, we are connecting to "My Community"

---------------------------
SELECT EnterprisePROJECT
---------------------------
  ID Name                   UUID
---- ---------------------- ------------------------------------
   0 My Enterprise Project    acebdf09-1234-4321-acdf-987697aed08f
   1 Other Enterprise Project 55555555-5555-5555-5555-555555555555
   2 YetAnotherProject      0a9b8c7d-6e5f-4321-1a2f-34678d9e0c8b
Select Project ID [create new]: 2

Enter the ID of the Enterprise Project you want to send documents to for translation.  In this example, we are using the "YetAnotherProject" project in the "My Community" community.  You can also just hit Enter with no input to create a new project in the "My Community" community and use it

---------------------------


SELECT WORKFLOW TEMPLATE TO COPY AS A NEW PROJECT WORKFLOW

---------------------------
  ID Name                   UUID
---- ---------------------- ------------------------------------
   0 Machine Translation    c675bd20-0688-11e2-892e-0800200c9a66
   1 Translation + 1 review 2b5498e0-f3c7-4c49-9afa-cca4b3345af7
Select workflow ID [Project Default]: 0

Enter the ID of the workflow you want to use for your project.  In this example, we are using the "Machine Translation" workflow.  You can also just hit Enter with no input to use your selected project's workflow. 

---------------------------
SET SOURCE LANGUAGE
---------------------------
Code   Locale Name
------ -----------------------------
xx-XX  Language, Country
en-GB  English, United Kingdom
en-US  English, United States
en-ZA  English, South Africa
es-AR  Spanish, Argentina
es-ES  Spanish, Spain
es-MX  Spanish, Mexico
[many other languages]

What is the default locale for your source content? [en-US]:en-US

Enter the code for the locale that you expect your original content to be in.  This is called the source locale.  In this example, we plan to send documents that are in American English and have them translated into other languages.  You can also just hit Enter with no input to use the default source language, which is American English (en-US)

What default target locales would you like to translate into (eg. fr-FR, ja-JP)? [None]: es-MX, uk-UA, ko-KR

Enter the codes for the locales that you plan to translate your content into.  These are called the target locales.  In this example, we plan to translate our documents into Mexican Spanish (es-MX), Ukranian (uk-UA), and Korean (ko-KR).  You can also just hit Enter with no input if you do not want to set any target locales at this time.

Where would you like translations to be downloaded? [.]: 

You can enter a directory that you want translations to be downloaded into.  This will be the download folder.  For example, if you set the download folder to ~/myproject/documents, and then uploaded ~/myproject/fileA.txt and ~/myproject/subdir1/fileB.txt, the translations for both fileA.txt and fileB.txt would be downloaded into ~/myproject/documents/.  You can enter an absolute path or a path relative to the current directory, which in this case is ~/myproject.  For instance, if you entered ~/myproject/subdir1/subdir2, it would be the same as entering subdir1/subdir2.  If you just hit Enter with no input or enter the current directory, no download folder will be set and translations will end up downloading to the same location as their sources.  For instance, if you uploaded ~/myproject/fileA.txt and ~/myproject/subdir1/fileB.txt, the translations for fileA.txt would be downloaded into ~/myproject/ and the translations for fileB.txt would be downloaded into ~/myproject/subdir1/.  In this example, we just hit enter with no input, which doesn't set any download folder.

Would you like to configure advanced options? [y/N]: N

The advanced options are git auto-commit, clone, auto-format, append, and download finalized file.  In this example, we are skipping these by entering N, which just sets the default values.  You can also just hit Enter with no input to skip the advanced options.  The only option that we really care about in this example is the clone option.  The default turns the clone option on, which changes the location that translations will be downloaded to.  When clone is turned on, locale folders are created for each target locale when translations are downloaded, and the translations are put into those locale folders.  The locale folders are created inside the download folder, or in the root of the project if no download folder is set.  Because no download folder is set in this example, all Spanish translations will be downloaded into ~/myproject/es-MX, all Ukranian translations will be downloaded into ~/myproject/uk-UA, and all Korean translations will be downloaded into ~/myproject/ko-KR, even if the source documents were in other directories.

You can change the clone option and the download folder by using the ltk config command as follows:

ltk config -d --none     //unsets the download folder
ltk config -d /user/Myself/Documents/MyTranslations     //sets the download folder to /user/Myself/Documents/MyTranslations
ltk config -c off     //turns the clone option off
ltk config -c on     //turns the clone option on

Round-Tripping Content

Key ltk Commands

Round-tripping refers to the whole process of uploading a document to Enterprise for translation, having it be translated, and then downloading the translations.  The main ltk commands that will be used for this are ltk add, ltk push, ltk list, ltk request, ltk status, and ltk pull.  There are other commands, which can be seen by running ltk -h, but in these basic examples we are going to stick with these six commands.  The other commands will be briefly touched on later.  The following examples will use the example setup explained in the section above and will assume that they are being run from the root of the project.

Examples of ltk add
ltk add fileA.html     //uploads ~/myproject/fileA.html if it exists to the "YetAnotherProject" project in the "My Community" community in Enterprise and adds it to the ltk project's local tracking.
ltk add /user/Myself/MyDocuments/A*.txt     //uploads all files in /user/Myself/MyDocuments/ that start with "A" and end with ".txt" to Enterprise and adds them to local tracking.
ltk add subdir1/subdir2     //adds the folder ~myproject/subdir1/subdir2/ to local tracking, and uploads all files in that folder to Enterprise and adds them to local tracking as well.
ltk add ~/myproject/fileA* subdir1     //for all files in the root of the project that start with "fileA" and all files in ~myproject/subdir1/, adds them to Enterprise and adds them to local tracking.  Also adds the folder ~myproject/subdir1/ to local tracking.

Examples of ltk push
ltk push     //for all locally tracked files that have been modified since they were last added or pushed, updates the versions stored in the Enterprise project.  For instance, if ~/myproject/fileA.txt contained the text "This is text" when it was added, the version in the Enterprise project would also say "This is text".  If the contents of ~/myproject/fileA.txt were changed to be "New content", the version in the Enterprise project would still say "This is text".  Running this command would update the version in Enterprise to match the local file and say "New content".  It also adds files that are in locally tracked folders that might not have been added themselves.  For example, if local tracking contains the files ~/myproject/file1.txt and ~/myproject/otherfiles/file2.txt and the folder ~/myproject/otherfiles/, but the local filesystem also had the files ~/myproject/otherfiles/file3.txt and ~/myproject/otherfiles/file4.txt, this command would add ~/myproject/otherfiles/file3.txt and ~/myproject/otherfiles/file4.txt to local tracking and upload them to Enterprise
ltk push -n     //lists the files that would be added and updated if this command had been run without the "-n" flag, but doesn't actually add or update them.


Examples of ltk list
ltk list     //lists all documents that are being locally tracked by the ltk project 
ltk list -r     //lists all documents that can be found in the "YetAnotherProject" project in Enterprise.  This is useful for finding out if all of the documents that you have added have successfully finished uploading yet 
ltk list -l     //lists the locale codes for the languages that Enterprise supports.  There are some cases where you need to input locale codes, and this will help you know which code to use for which language


Examples of ltk request
ltk request     //begins the translation process into all default target locales for all locally tracked documents that have successfully been uploaded to Enterprise.  In our example, this would start translating everything that's been added and successfully uploaded into Spanish, Ukranian, and Korean
ltk request de-DE el-GR     //begins the translation process into German (de-DE) and Greek (el-GR) for all locally tracked documents that have successfully been uploaded to Enterprise
ltk request -p ~/myproject/textfile.txt     //begins the translation process into all default target locales for ~/myproject/textfile.txt.  In this example, it would translate ~/myproject/textfile.txt into Spanish, Ukranian, and Korean, so long as ~/myproject/textfile.txt had been added and successfully uploaded first.
ltk request -n textfile.txt     //same as the above example with the "-p" flag, except it uses a name instead of a filepath.  Usually, the name is the name of the file itself, while the filepath includes the directories to reach that file.  For example, a file with the path /user/Myself/MyDocuments/textfile.txt would have a name of "textfile.txt".  However, because you can have a file with the same name stored at different filepaths, it's possible to add different files with the same name.  Because of this, it is recommended to use the "-p" flag with a filepath instead of the "-n" flag with a name because you can be more explicit in specifying which document you want to request.
ltk request -p subdir2/textfile2.txt de-DE el-GR    //begins the translation process into German (de-DE) and Greek (el-GR) for ~/myproject/subdir2/textfiles.txt, so long as it had been added and successfully uploaded first.

Examples of ltk status
ltk status     //displays the overall completion percentage and status of each locally tracked document.  A percentage of 100% or a status of COMPLETE means that all translations that have been requested are completed.
ltk status -d     //displays a more detailed breakdown of the completion percentages and statuses for each locally tracked document.  This more detailed breakdown includes the completion percentage and status for each individual requested translation.  For example, there could be a document that has been requested in Spanish, German, and Italian.  If the Italian translation for that document is halfway done, the German translation is all the way done, and the Spanish translation hasn't been started yet, the overall document status will be IN PROGRESS, but the status for the German translation specifically will be COMPLETE  
ltk status -n textfile.txt     //displays the overall completion percentage and status for the document with the name "textfile.txt".  As explained above, it is possible to have duplicate names in local tracking and in the Enterprise project, so this should only be used if you are sure that there are no duplicate names.  This also assumes that a file with the name "textfile.txt" has been added to the ltk project already
ltk status -n textfile.txt -d     //displays the more detailed breakdown of the completion percentages and statuses for each requested translation for the document with the name "textfile.txt".  As explained above, it is possible to have duplicate names in local tracking and in the Enterprise project, so this should only be used if you are sure that there are no duplicate names.  This also assumes that a file with the name "textfile.txt" has been added to the ltk project already

Examples of ltk pull
ltk pull     //downloads all the translations from the Enterprise project for all locally tracked documents.  If a translation has been started but is not yet complete, the incomplete file will still be downloaded.  The download locations will depend on the config settings.  See the above explanation of the example ltk project setup to see how the different config options affect the download locations.  If the clone option is turned on, the filenames of the translated files will be the same as the source files.  For example, the Japanese translation of a file named "file1.json" would still be named "file1.json".  If the clone option is turned off, the filenames of the translated files will have the target locale appended to them.  For example, the Japanese translation of a file named "file2.json" would have the name "file2.ja-JP.json".
ltk pull ko-KR uk-UA     //downloads the Korean and Ukranian translations from the Enterprise project for all locally tracked documents.  If a translation has been started but is not yet complete, the incomplete file will still be downloaded.  The download locations and file names will depend on the config settings.

Round-Tripping Examples

All of these examples use the ltk project setup demonstrated previously

Case 1:

I want to translate a single file from (American) English into all three of my target languages ((Mexican) Spanish, Ukranian, and Korean).  I have never added anything before, so my local tracking is empty.
Source document location: ~/myproject/fileA.txt
Desired translation locations: ~/myproject/es-MX/fileA.txt, ~/myproject/uk-UA/fileA.txt, ~/myproject/ko-KR/fileA.txt
Current directory: /users/Myself/

cd ~/myproject     //change directory to the project root
ltk add fileA.txt     //add the source document by using its path relative to the project root
ltk list -r     //look for fileA.txt in the output to verify that it was sucessfully uploaded.  If it is not in the output, wait a bit and re-run this command until it is before proceeding.
ltk request     //because the only added file is fileA.txt, we can just run this without specifying fileA.txt specifically
//give Enterprise time to translate the file
ltk status     //check on the status of fileA.txt.  If it displays 100% (COMPLETE), it is ready to download.  If it doesn't, wait a bit and re-run this command until it does before proceeding.
ltk pull     //because the only added file is fileA.txt and we want all the translations, we can just run this without specifying fileA.txt or the translation locales specifically

Case 2:

I have a personal project called Alpha that I have stored in ~/myproject/alpha1.0 that contains multiple directories and multiple files.  I want to translate everything in Alpha into German.
Source document locations: ~/myproject/alpha1.0/fileA.txt, ~/myproject/alpha1.0/sub1/fileB.txt, ~/myproject/alpha1.0/sub1/sub2/fileC.txt
Desired translation locations: ~/myproject/de-DE/fileA.txt, ~/myproject/de-DE/fileB.txt, ~/myproject/de-DE/fileC.txt
Current directory: ~/myproject

ltk add alpha1.0     //add the folder as well as all files under it, including files in subdirectories.
ltk list -r     //look for all the Alpha project files in the output to verify that they were successfully uploaded.  If they aren't in the output, wait a bit and re-run this command until they are before proceeding.
ltk request de-DE     //specify that we want all the files to be translated into German (de-DE)
//give Enterprise time to translate the files
ltk status     //check on the statuses of the files.  When they all display 100% (COMPLETE), they are ready for download.  Until they do, wait a bit and re-run this command until they do before proceeding.
ltk pull     //Because German is the only requested target language, we don't need to specify it here.


Now I've edited the contents of ~/myproject/alpha1.0/sub1/sub2/fileC.txt and I want to get a translation of the updated contents

ltk push     //updates all changed files, which in this case is just fileC.txt.  Because fileC.txt was previously requested, it will automatically start re-translating the updated content
//give Enterprise time to re-translate the file
ltk status     //check on the status of fileA.txt.  If it displays 100% (COMPLETE), it is ready to download.  If it doesn't, wait a bit and re-run this command until it does before proceeding.
ltk pull     //This still downloads the translations of fileA.txt and fileB.txt in addition to the updated translation for fileC.txt, but that's okay because they're still correct and current translations.

Case 3:

I have a personal project called Alpha that I have stored in a Git repository and have downloaded.  I renamed the repository folder to "myproject" and then ran the ltk project setup demonstrated above.  There are a ton of files and folders in this project, but I just want to translate the files with the extension ".resx".  The deepest nested ".resx" file is ~/myproject/branchB/branchC/branchE/resource5.resx.  I make a develop branch off of the master branch to make changes, then translate from the develop branch, and then merge the changes and new translations back into the master branch.  I want to translate those ".resx" files into Canadian French (fr-CA) and Swiss German (de-CH), and I want the translated files to end up right next to the source files.
Source document locations: ~/myproject/resource1.resx, ~/myproject/resource2.resx, ~/myproject/branchA/resource1.resx, ~/myproject/branchB/resource1.resx, ~/myproject/branchB/other/resource100.resx, etc.
Desired translation locations: ~/myproject/resource1.fr-CA.resx, ~/myproject/resource1.de-CH.resx, ~/myproject/resource2.fr-CA.resx, ~/myproject/resource2.de-CH.resx, ~/myproject/branchA/resource1.fr-CA.resx, etc.
Current directory: ~/myproject
Current git branch: develop

ltk config -c off     //turns off the clone option that had been turned on by default when the ltk project was set up
ltk add *.resx */*.resx */*/*.resx */*/*/*.resx     //These four fileglob patterns will match every .resx file in the Alpha project because the deepest .resx file is three directories below the ltk project root

I do some work on the other files on the develop branch.  I modify a few of the .resx files too.

ltk push     //update the .resx files that had been modified
ltk list -r     //look for all the Alpha project .resx files in the output to verify that they were successfully uploaded before proceeding.  If they aren't, wait and re-run until they are.
ltk request fr-CA de-CH     //specify that we want all the files to be translated into French (fr-CA) and German (de-CH)

I make a few other changes on the other files on the develop branch while I wait for Enterprise to finish translating my files, but none of the modified files are .resx files.  I also want to keep my changes to the code and source .resx files separate from my changes to the translations

ltk status     //check on the statuses of the files.  When they all display 100% (COMPLETE), they are ready for download.  Until they do, wait a bit and re-run this command until they do before proceeding
ltk pull     //we want all the translations for all the files, so we don't need to specify anything extra here
git add *.*.resx */*.*.resx */*/*.*.resx */*/*/*.*.resx     //stage only the new and changed translations for the commit.  The extra "*." before "resx" ensures that the only files that match are ones with locale codes (see the paths in the desired translation locations above), which indicate that they are translations
git commit     //commits the translations

I make a few final changes to the code on the develop branch.  I test my develop branch and it passes my requirements, so I'm now ready to update the master branch

git add -A     //stage all the other currently changed/added/deleted files for commit
git commit     //commit the changes
git push     //push the commits on my develop branch up to the repository
git checkout master     //check out the master branch in preparation for merging into it
git pull     //make sure the master branch is up to date before merging
git merge develop     //merge the develop branch into master

My next improvement to my Alpha project involves adding another .resx file at ~/myproject/branchC/feature/resource1.resx

git checkout develop     //goes back to the develop branch to make my changes

I create the .resx file as well as make the other files and changes that I need for my new feature.  Those changes included modifying a few other .resx files that had already existed.

ltk push     //update the .resx files that had been modified
ltk add ~/myproject/branchC/feature/resource1.resx     //add the new .resx file
ltk list -r     //verify that all files I want to translate have been uploaded successfully
ltk request -p ~/myproject/branchC/feature/resource1.resxfr-CA de-CH     //request translations for the new .resx file.  The others still have the targets requested, so we don't need to re-request them
ltk status     //check the statuses of the files.  When they all display 100% (COMPLETE), they are ready for download.
git add -A     //stage all changes for commit, which in this case is only the non-translation changes for commit
git commit     //commit the changes
ltk pull     //download the new translations
git add -A     //stage all changes for commit, which in this case is only the translated changes for commit
git commit     //commit the changes

Advanced Usage

There are many more commands and command flags that the filesystem connector can use.  For example, if you want to specify that a certain file should go through a different workflow than the default one set when the ltk project was set up, you can use the "-w" flag with a workflow id when you use the ltk request command.  A workflow is a series of steps taken when translating a document.  If you want to cancel a document and remove it from local tracking, you can use the ltk rm command.  Cancelling a document stops all work on all translations for that document.  If you change your mind and want the document to be translated after all, you'll need to reupload it.  Using ltk -h will display a list of commands, and using the flag "-h" after any command will display help information for that command.  The following is a brief summary of what each command can do with the right flags:

ltk add - add files and folders to local tracking and upload them to Enterprise, set or upload filters to be used with the file(s) being added, force Enterprise to see the file(s) as a certain filetype, indicate the file(s) encoding, send metadata with the file(s), set a target download folder for a document's translations that overrides the config options
ltk clean - remove files that don't exist anymore from local tracking and cancel them in Enterprise, remove files that have been cancelled or deleted from Enterprise from local tracking, delete files when they are removed from local tracking, cancel all locally tracked documents and clear local tracking
ltk clone - copy the subfolders of added folders into the locale folders
ltk config - change the options that were set when the ltk project was set up, including the advanced options
ltk download - download translations for specific files, download only translations in certain languages for certain files, force the translated files to have the locales appended to their names, force the translated files to not have the locales appended to their names (will not overwrite, so this probably shouldn't be used unless all the translations and the source are going to have different paths), download XLIFF files instead of the translations themselves.  May not overwrite translations that have previously been downloaded
ltk filters - upload filter files to Enterprise, download filter files from Enterprise, get a list of filters you have access to on Enterprise, remove filters from Enterprise, update filters on Enterprise
ltk import - download source documents that were uploaded to Enterprise, automatically add imported documents to local tracking
ltk init - set up an ltk project and connect it to an Enterprise project, set certain values like your access token or client_id, set up the project in a different directory than your current directory, authenticate using a browser window, delete the current project, reset access tokens
ltk list - show a list of locally tracked documents, show a list of documents by their names instead of filepaths, show a list of locally tracked directories, show a list of available workflows, show a list of supported locales, show a list of supported formats, show a list of available filters, show a list of documents in the Enterprise project
ltk mv - move a file to somewhere else (If you move a file that is being locally tracked without using this command, local tracking will no longer know where it is and this may cause problems)
ltk pull - same as ltk download, except it doesn't have the option to download XLIFF files but does have the ability to download all translations for all locally tracked files without specifying them all individually.  Also overwrites translations that have previously been downloaded.
ltk push - updates documents that have been added if they have been modified, adds documents that haven't been added but are in added folders, does a test run and displays the results without actually pushing anything
ltk request - request translations for documents that have been added, cancel a translation in Enterprise, delete a translation in Enterprise, set a due date for a translation, set a workflow for a translation that overrides the one set when the ltk project was set up
ltk rm - remove a document(s) from local tracking, remove a folder from local tracking, cancel a document(s) in Enterprise, delete a document(s) in Enterprise, delete a document(s) locally, delete a document by id (allowing you to delete documents that aren't locally tracked so long as you can get the id number)
ltk status - display the overall progress that's been made on translating all locally tracked documents, display a detailed breakdown of the progress on all the translations of locally tracked documents, show the status of a specific document, show the status for all documents in the Enterprise project even if they aren't locally tracked
ltk watch - watches added folders and automatically adds/pushes new/changed documents in those folders and downloads completed translations (this loops forever, so it should be run as a background process), watches while ignoring files with specified extensions, adjust the amount of time between polls to Enterprise, ignore new files and only watch already-added files

Automation

One of the advantages of the filesystem connector is that, as a command line utility, it is easy to use in automation.  The following are some suggestions when automating filesystem connector operations:

Uploading, Requesting, and Downloading documents:

You need to make sure that documents have finished uploading before you can request them.  One suggestion for how to do that is to look for the id numbers of the added files in the list of files found in the Enterprise project.

output = ltk add file1.txt   //store the output of ltk add in the variable output
IDnumber = regex match for "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" in output   //if file1.txt is successfully added, the output would be something like "Added document file1.txt with ID f09b7248-3dae-41ba-9cf0-68761c762e21"
if IDnumber found:
     uploaded = false
     for i = 0, i < 20, i++:   //In this pseudocode, I'm limiting my program to twenty attempts, but you can choose whatever limit you want
          list = ltk list -r   //store the output of ltk list in the variable list
          if IDnumber in list:   //if the IDnumber string can be found in the list string, then the file is uploaded
               uploaded = true
               break   //the ID number was found, so we can break out of the for loop
          sleep for 1 minute
     if uploaded:
          ltk request
     else:
          print "File was added but not uploaded"
else:
print "File failed to be added"

To download translations when they are finished, a simple solution would be to periodically check the status and then pull when everything shows 100%.

while true:
     output = ltk status   //store the output of ltk status in the variable output
     ready = true
     for each line in output as line:   //read the output one line at a time, storing the current line in the variable line 
          percent = regex match for "\): ([0-9]{0,3})% \(" in line   //a line of status output looks like "Status of file1.txt (f09b7248-3dae-41ba-9cf0-68761c762e21): 50% (IN PROGRESS)", so this regular expression will match the area where the percentage is stored and extract the percentage amount
          if percent != 100:
               ready = false
               break   //at least one file isn't ready, so we know we have to keep waiting and we can stop checking the output
     if ready:
          ltk pull
          break   //we want to break out of the while loop so we don't continue to loop and re-pull the translations every minute
     else:
          sleep for 1 minute