Introduction #

In order to work with files in XLOC, they need to be uploaded. To do that, first we need to create a File Type. If you haven't already done so, you can see the guide on how to make a File Type by clicking here.

If you already have a File Type setup, you can proceed with this guide to learn how to upload files!

Basic Guide to Uploading Files #

These sections will cover the basics of everything you need to upload files. The Supplemental Information section below will go into more detail of the various parameters and optional settings, so please check that if you’d like to learn more!

File Registration #

When uploading a file to XLOC, it needs to be registered as a Source Asset so that XLOC knows how to handle it. There are two methods for registering a file, automatic or manual. Each have situations where they can be useful.

Automatic File Registration #

This option is especially useful in cases when you have lots of files to work with. To avoid having to manually register each file one by one, the files can be put in a zip file and uploaded all at once and XLOC will automatically register the files.

How to Automatically Register files #

First we need to set a default File Type so that XLOC will know how to handle files it has never encountered before. To do so:

1. Select the Producer tab
2. Click on the arrow beside Project in the left menu to expand the menu, and then click on Upload Settings
3. At the bottom of the screen you will see a list of file types available on the project. Find the one you want to use and click on Edit
4. In the input box, enter the extension of the file(s) you are trying to upload. For example if you are working with XLSX Excel files, input .XLSX
   *If you have a mix of .XLS and .XLSX files, you can input just .XLS and it will handle both

1. What this does is basically tell XLOC “If you see a file that you have never seen before, and it has the extension .XLSX, use this File Type to handle it”
2. Click on OK and then click Apply Changes at the bottom of the screen to save the settings
3. Now the file can be uploaded (see the Uploading Files section for details)

Once the files have been uploaded, they will also be registered at the same time. After that they can be accessed from the Source Assets page, where they can be edited or deleted.

See the Editing Source Assets section for more details on what parameters can be edited.

Manual File Registration #

Registering a file manually can be useful in cases when you have just one file to work with, and can make it easier to customize certain parameters of the file. For example, when using automatic File Registration, the file name will automatically be added as a Prefix to all string IDs, but when manually registering a file this Prefix can be customized or excluded entirely.

How to Manually Register Files #

Select the Producer tab

Click on Source Assets in the left menu

Click on Register File in the top right of the page

Fill in the necessary parameters:

1. Name - This is a name for internal XLOC usage so you can tell which file is which. It doesn't necessarily need to be the name of the file itself but in most cases that's the simplest
2. Output Name - This needs to be the exact file name, including its extension (for example .XLSX, .po, etc.)
   *You can use the wildcard character * in the Output Name as well in cases where you will have multiple iterations of the same file. See the Import Name section below for more details
3. Other parameters when registering the file are not mandatory and can be ignored in most cases

1. 

Click on Update at the bottom of the page

After clicking Update, several new parameters will be displayed

1. For now we only need to check the File Type parameter. If your project has only one File Type assigned to it then your registered file should default to that, but if your project has multiple File Types you can change which one the registered file should use here.

1. 
2. Further details on what parameters can optionally be changed can be found in the Editing Source Assets section

Once it’s been confirmed that the correct File Type is designated, click on Update at the bottom of the page again. You should be brought back to the Source Assets page, and see the file you registered there

1. 
2. Now the file can be uploaded (see the Uploading Files section for details)

Differences Between Automatic and Manual File Registration #

For the most part both methods work the same, but there are some differences to be aware of:

1. When using automatic registration, the resource Prefix will automatically be set to use the file name, whereas with manual registration will default to having no prefix
2. When using automatic registration, the file type needs to be set in Upload Settings, whereas with manual registration the file type needs to be set when editing the Source Assets

Uploading Files #

Once you’ve registered your file(s) or set it up for automatic registration, the files can be uploaded. When uploading files, the upload must be performed at least two times; the first time will be to upload the Source and Source information, and the second time will be to upload Translations and Translation information.

Uploading Source #

Select the Producer tab

Click on the arrow beside Source Assets in the left menu to expand the menu, and then click on Upload

Click on Select a File and choose the file you want to upload. Do not check the Uploading Translation checkbox when uploading the Source

1. If you have multiple files to upload, put them in a zip file and choose that instead
2. You can also drag and drop the file from a folder on your computer to the Upload page

1. When uploading Source, make sure the Uploading Translation checkbox is not checked!

Click on Upload File. You will be brought to a screen that says the upload is in progress. Depending on the size and number of files this may take some time, so just wait until it finishes processing. You can click on “Attempt to Cancel” to cancel it, but depending how far into the process it is this may or may not be possible

*At this point the files are not actually being uploaded, so don't worry if any mistake was made. You will have a chance to review the upload details before the upload actually begins

After some time, an Approval screen will appear with some information and several buttons

*Please see the Approval Page Information section below for details on what each field and button is for

Confirm the information, if all the numbers are 0 it means something has gone wrong as no strings were found; if this happens, please check the Details and double-check that your File Type and File Registration have been set correctly

1. It’s a good idea to click on Details to check for errors and warnings as well before Approving the upload
   *See the Upload Details section below for more details on how to read and resolve issues in Details files

If everything looks OK, click on Approve to proceed with uploading the file.

1. If there are any Errors or Warnings, a confirmation pop-up will appear after clicking Approve to let you know; in this case it’s recommended to check the Details to see what the Errors/Warning are before proceeding

1. 1. 
2. After approving, it will take some time to process, and then you will be returned to the Upload page. Now you can upload the translations!

Uploading Translations #

The process for uploading Translations is the exact same as the steps above for uploading Source, with one difference; in Step 2 check the Uploading Translation checkbox, and select the language(s) that you want to upload translations for.

Supplemental Information #

This section of the guide will focus more on additional information and optional parameters; it is not necessary to use all of the information when uploading files, but can be used as reference when troubleshooting or trying out different file setups.

Approval Page Information #

There are various pieces of information and buttons in the Approval Page; this section will explain what each is for and what to look out for.

Information Columns #

The columns with numbers all (with the exception of the Affected column) refer to the number of strings in that category, with the number of words in parenthesis. The format is # Strings (# Words)

In most cases, the main thing to look out for in the information columns is to check that the numbers seem reasonable for what you are trying to upload. For some common examples:

• If all the numbers are 0, it means no strings were found and something went wrong
• If you are uploading a new version of a file that should have lots of changes compared to the previous version, but it shows 0 or a small number in the Updated column, something might have gone wrong or the wrong version of the file might be getting uploaded

Below is a description of what each field refers to:

• Name and Date - The name of the file being uploaded and the date/time the upload was initiated
• Version - This can be ignored in most cases
• Total - Total number of strings (words) being uploaded
• New - Number of new strings (words) being uploaded
  • For Source uploads, a string is considered New if the string ID did not exist in previous versions of the file
  • For Translation uploads, a string is considered New if the string did not previously have a translation
• Updated - Number strings (words) that were updated compared to the previous version of the file
  • Note, the (words) count does not indicate how many words were changed, it will just display the total word count of the strings which are considered to be Updated
  • A string is considered Updated if there was already an existing string in a previous version of the file, and the Source/Translation was changed in any way in the new upload
• Unfound - Number of strings (words) that existed in the previous version of the file, but could not be found in the file currently being uploaded
  • This can occur in cases when a string ID or Source text has been removed from a file
  • There are various options for how XLOC handles strings that are Unfound, please see the Unfound Strings section in the Upload Settings guide below for more details
• Affected - The left number shows the number of New strings, while the number in parenthesis shows the number of New words; this is basically a summary of the New and Updated columns, to show # New Strings (# New Words)

Buttons #

• Details - Click this button to see the details of the upload. See more information on this and how to read the file it outputs in the Upload Details section below
• Source - Click this button to download the file that is being uploaded, in case you need to confirm that the correct file is being uploaded
• Approve - Click this button to start the upload, if everything about the upload looks OK
• Reject - Click this button to cancel the upload, in cases where there are errors or other issues. You will be brought back to the main Upload page and can re-upload the file after addressing the issue(s)
• Go to Source - This button is not used and can be ignored

Editing Source Assets #

To edit a source asset, navigate to the Source Assets page and click on the pencil icon beside the source asset you want to edit.

There are various parameters which can be edited, please see below for information on some of the more commonly used parameters.

Name #

This is a name for internal XLOC usage so you can tell which file is which. It doesn't necessarily need to be the name of the file itself but in most cases that's the simplest

Output Name #

This will be used as the name of the file when it is rebuilt. It should include the extension at the end of the name as well (for example .xlsx)

• When registering the file, it’s recommended to make this identical to the name of the file being uploaded (including the extension) because the import name defaults to the same name, and the import name must be the same as the file being uploaded.
  • However, once file is Registered and the import name is set, the output name can be customized in case you want the file name to be different when it's rebuilt.

Import Name #

This must be the same name as the file which is being uploaded, including the extension.

• You can use the wildcard * which represents any other characters, to avoid needing to edit the name every time a change is made to the file name.

• 
• For example, if you work with a new text file weekly and the file name includes the date, you can replace the date in the output name with a * so that XLOC can handle future uploads of the file even if the date changes.
  • For example:
    TextFile_0207.xlsx
    TextFile_0214.xlsx
    TextFile_0221.xlsx
    If you register the file with the import name TextFile_*.xlsx, it will be able to handle all 3 files and treat them as the same file

File Type #

If your project has only one File Type assigned to it then your registered file should default to that, but if your project has multiple File Types you can change which one the registered file should use here.

Resource Prefix #

This allows you to add a prefix which will be added to the start of every string ID that is uploaded from the registered file.

• This can be useful for example if you want to include the file name as part of the string IDs to help differentiate them, in cases where multiple files have the same IDs

• In this example, every string in the file will have “File_Name_” added to the start of it
• Please be aware that if you are working with a client who is not also using XLOC, adding a Resource Prefix to the string IDs might cause a mismatch between the string IDs you are using and what they have on their side, so be sure to communicate this to avoid any confusion when string IDs are included in change logs, bug reports, etc.

Groups #

This can be used to add all strings from a particular file to a Group. Select a group from the dropdown and click on Add to Group to add it. This will immediately add all strings from the related file to the chosen group.

Other Settings #

There are various other settings that can be adjusted in the Source Assets edit page, but they are rarely used outside of specific scenarios and are therefore outside the scope of this guide. In most cases, leave them as their default settings.

Active #

By default this will be set to Yes; you can set it to No if you don’t want the related file to appear in search results.

• This can be useful for example if you are uploading a Glossary file that you want to use for Verification Checks, but don’t want the strings from the Glossary to appear in search results

Include in Build #

Similar to the Active option, it will default to Yes; set it to No if you don’t want the related file to be included when you rebuild files.

• Again this can be used when you are uploading reference files that you want to be available for reference but don’t want to include in rebuilt files
• 

Validators #

You can add Validators that will be run when rebuilding the related file. Errors and warnings generated by the validators will be viewable in the Details after rebuilding the file.

Please see the guide for Validators for more information.

TODO: Add link to Validators guide when it’s ready #

Others #

The other options in the Source Assets page are more advanced and rarely used; please consult the XLOC manual or reach out to the Tech Support team if you’d like to learn more about the other Source Assets options.

Upload Details #

This section will provide some information on how to read the files output by using the Details button on the Upload Approval page.

Details files can be output as either TXT files or Excel files. The default is TXT but this can be changed in Project Settings (accessed from the Producer tab and then clicking on Project in the left menu)

For the guides below, the screenshots will show how things look in the TXT version of the files, but the principles remain the same in either file format.

Basic Information #

Regardless of the file format, there will be a quick summary of the upload available.

The main thing to look for is if there are any Errors or Warnings, as well as Strings not found. These should be looked into before approving an upload. In some cases they can be ignored, but especially if it's the first time uploading a file it's important to check to make sure.

Along with Errors and Warning you can find information about what files and tabs were uploaded and how many strings were affected by the upload.

Scrolling through the Details file, you can see information on the file being uploaded, which File Type is being used, which tabs of the file are being uploaded, and which specific strings are being added or updated. These can all be useful for helping to understand what might have gone wrong in cases where the upload results are not what are expected.

How to Find Errors and Warnings #

If your Details file indicates that there are any Errors or Warning:

• If you are using Text files for Details, use CTRL + F to search the file for "ERROR" or "WARNING" to find it. It will help to use "Match Case" in the search to avoid finding strings that contain those worse.

• If you are using Excel files for Details, you can find a list of the WARNINGS and ERRORS on the Details tab of the file
• 

Understanding Errors and How to Resolve Them #

There are several errors that can occurs when uploading files to XLOC. While this will not be a comprehensive list, these are the most common errors that occur. If you encounter errors or warnings that you are not sure how to handle, please don't hesitate to reach out to XLOC support for help dealing with them.

In general:

• ERRORS are more severe and in most cases should be resolved before approving an upload; there are of course exceptions to this and in some cases ERRORS can be ignored
• WARNINGS are more situational and may not require any action to resolve depending on the situation; the purpose is more so to flag things that look suspicious and are worth double-checking

If an ERROR or WARNING needs to be resolved, please Reject the upload, resolve the issue, and then re-upload the file.

ERROR: found dupe instance of RSID: {0} #

This error will occur when there are strings which have the same string ID. If this happens, only the first instance of the string will be uploaded and the following instances will be skipped.

• 
• There are several ways to resolve this:
  • If the duplicate string IDs are in the same file:
    • Edit the File Type to add additional parameters to the ID (see the guide here for more information)
    • Edit the File Type and check the "Upload Duplicates" checkbox
  • If the duplicate string IDs are in a different file:
    • Edit the Source Asset and add a Prefix to the string ID

ERROR: sheet {0} not valid for import from this language. #

This error will occur if you are trying to upload translations for a language which is not handled by the designated File Type

• 
• To resolve this, double-check the File Type settings and make sure the target language is included in it and set to the correct column

WARNING: Line {0} ID contents are missing from column {1} #

This warning will occur if a line in the uploaded file has a blank cell in the Resource ID column, but still has Source text in that row

• If a row is missing both the Resource ID and Source but contains translations on that row, this warning will not be triggered and the line will simply be skipped (It will be marked as an Unfound string)

• • In this example, Lines 15 and 21 have been flagged, but not Line 8 because Line 8 is missing both String ID and Source
• To resolve this, double-check the file being uploaded to check if the Resource IDs are intentionally blank or not; if so then the Warning can be ignored, if not then please correct the Resource IDs in the file and re-upload

WARNING: Shifting RSIDs #

There are two variations of this warning:

• This string is changing from one that has previously been imported.
• This string is changing from something that we have previously modified.

• • 
• These warnings will occur when the text of a string has been changed, while the previous text was moved to a different resource ID
  • For example in the screenshot above, the string Animal_1 was changed from Cat → dog, while Animal_2 was changed from dog → Cat
  • It’s possible that such an occurrence could be caused by an accidental swap of text between strings that wasn’t meant to happen, so a warning is triggered to let users know
• In many cases no action is needed to resolve this and it can be safely ignored, but it is worth double-checking the affected strings to ensure that no un-intentional text swaps occurred

Upload Settings #

Upload Settings can be found in the Producer tab, under Project in the left menu. There are various settings that can be configured for uploading files.

After applying any changes, be sure to click the Apply Changes button at the bottom of the page to save any changes made.

Unfound String Behavior #

Unfound strings refers to strings which were present in a previous version of the file, but in a new upload they are missing. This can occur either if the string ID cannot be found in the new file, or the source text is blank in the new file.

This setting will determine how XLOC handles unfound strings:

• Ignore - This is the default behavior. It will cause the unfound Strings to be ignored; they will not be displayed in the upload Details or deleted and will simply be ignored.
• Display - This is the default setting, and will cause the affected strings to be listed as Warnings in the Upload Details. This is useful when you want to preserve the strings but still want to easily check which strings were unfound. It will display in the Details as follows:

• The format is Resource ID: Source text
• Manager Lock - This will Lock any unfound strings, making them only visible to Producer or higher access users. From there, Producers can review the strings and unlock them or handle them as needed.
• Delete - This will delete any unfound strings. This is useful in cases when previous versions of the file contain redundant or outdated strings that are no longer used and have therefore been removed from the text file. Setting this to Delete will cause the unfound Strings to be deleted from XLOC when the file is next uploaded, which can help keep the database clean and free from unused strings.
  *After using the Delete option, the setting will automatically change to Display after the next upload, regardless of whether the upload is approved or not; therefore if you want to use Delete for each upload, this setting will need to be changed and applied each time

Create Group on Import #

• None - No groups will be created upon uploading a file
• New Strings Only - Upon approving an upload, a Group will be created which contains all of the New strings in the upload
• New/Updated Strings - Upon approving an upload, a Group will be created which contains all strings that were either New or Updated in the upload

Groups that are created via this method will appear in language search pages under the New or Updated Groups filter, with a date/time stamp in the group name corresponding to the upload time so users can easily filter for the strings based on the upload date/time.

Auto Add #

Please see the section above for Automatic File Registration for information on the Auto Add function.

Other Settings #

There are several other settings available in Upload Settings but they are rarely used and can be left as the default in most cases.

Include Scripts in Build #

This can be ignored in most cases and left as the default “No.”

Log Notes Changes #

This option will include changes to String Notes, Translation Notes, and Translation Status in Upload Details, in case you want to track changes to that metadata in addition to source/translation changes.

String Notes update

Translation Notes and Translation Status update

Clear Locked Strings on Import #

Using this option will cause all Locked strings in the file to become Unlocked. This applies to all strings related to the file, even if the they are Unfound strings in a given upload and no longer exist, so please be sure to use this option only if it’s desired to unlock all strings from the file.
*Because of this, using this option in combination with the Manager Lock option for Unfound String Behavior makes them cancel each other out, as the Manager Lock option will Lock all unfound strings, but then this option will unlock them.

Unlocked strings can be Locked again by a Producer.

Approve 0 Errors #

Using this option will automatically approve and uploads that don’t contain any errors.
*Please be aware that even if there are WARNINGS in the upload, if there are 0 ERRORS then it will be automatically approved while using this option.

Deleting Files #

Files can be deleted if they are no longer needed or if a mistake was made during upload and it needs to be cleared out. Note that deleting a file will clear out all source text and translations for that file.

To delete a file:

1. Go to the Producer tab
2. Click on Source Assets in the left menu
3. Click on the pencil icon beside the file that you want to delete
4. Scroll to the bottom and click on Delete
   *It may take a bit of time to process the deletion