insert

insert

The insert function is similar to certain forms of the <&placefile: function in that it can insert text at specific locations. But <&insert: can insert text that is supplied as an attribute as well as special strings such as Adobe InDesign or Adobe InCopy text variables and other internal data such as page name, color, or content type.

Compared to text based PlaceFiles, <&insert: is easier to setup and use. Also, the Translate Script section of the rulesets can handle a much longer string of text compared to what you can insert into either of the replacement fields of a ruleset. Thus, to prevent needing to break a really long string of boilerplate text into multiple rules, you could use: <&insert:(text,

Most useful version of <&insert:

The original purpose of <&insert: was to add to the text being translated the publication code of the active page. Then from that inserted code, jump to rulesets specifically designed for handling those publication code. Here is an example from the top of a client ruleset:

Other practical uses for <&insert:

Since both the page's section letter and page number can be inserted into the asset being translate, then the translation can become special for certain sections, or more commonly for the first page of the section.

For example if the page was ‘01’ then you might want to use a different color for kickers. Or if a column ran on page ‘01’ then you might import a color column sig versus a black and white version. We know of sites that use unique date lines on section fronts and this too can be automated using <&insert:

Some sites have specific pages for specific content. Besides pleasing the readers to have consistent placement, it also makes it possible to do certain translations.

For example if the Opinion page runs on A4, then you can use that information to handle assets on that page uniquely as opposed to relying up other tags.

Other oddities

Because it can insert text into an asset, this could be used to do things like force bylines or taglines that would normally be handled by regular ruleset functions. What's unique here is the access to the various locations. Normal translation doesn't have many options to to location things - usually just the start or end of the <content> tags. But <&insert: can go to specific paragraphs if that is helpful. 

Insertion order

If you are inserting multiple items, keep in mind that the first one inserted will be the last one in text to translate. Here is an example Translate Script portion with 3 insertions that don't specify placement locations.

<&insert:(pubcode)>|<&insert:(ncd,S)>|<&insert:(page)>

The result for a document named ‘TRN_2013-02-14_B_009’ would be this combined string:

<page>9</page><ncd/S>B</ncd/S><pubcode>TRN</pubcode>

Notice that that effectively places the items in reverse order.

Surrounding Tags

As shown in the above example, the inserted text is always wrapped in tags that match the insert function’s p1, and p2 parameters. If p2 is used it will be prefixed by a / (forward slash) as shown in the ncd example above.

Function Details

The table below shows the details for the <&insert: function:

Insertion Types

The following Types of text can be inserted:

Additional Notes

automated

This doesn't indicate that the translation came from an Automated Production placement. Just that Automated Production is enabled on the current domain. However, the source will be set to `automated`.

color

This has three values. It will be `true` when the page is marked as color. It will be `false` if it is marked as black and white. It will be `null` if the page's color hasn't been indicated.

distributed

Has three options. `Normal` is what you would normally see. `Local` and the more common `Remote` are the two other options. No idea what this might actually be usable for. 

naming, ncd, & variable

These 3 have lots of overlap! naming and ncd are 100% the same. Consider ncd just a shortcut or abbreviation for naming. The options that are available are listed in the link below:

In addition to those, it might be possible to reach other semi-hidden options from the publication details such as:

• isDaily_b
• pubDate (has a fixed YYYY-MM-DD format)

If you need something, please file a support ticket to request it.

variable, however, is different because it can see things that are unique to Adobe InDesign. Below is an image of the default Adobe InDesign text variables that can be inserted. 

source

The source can change during translation from the initial source to `recursive`. If you want to use it to know that the translation started from a text file translated with `translateToEnd` called by a utility like `Translate Existing Text` you should use the <&insert:(source)> in the default ruleset.

This would be most useful for handling translations from Automated Production. Those translations would be marked with a source of `automated` and this could be used to modify `copyfit` or `headfit` options. As of 2022.08.12 `automated` would only appear on Automated Production translation of Article assets. 

type

Type is used for Page Content Types. And since a page can have from 0 to many Page Content Types, there can be between 0 and many <type> tags inserted.

Placement Locations: p3, p4, p5

The final three parameters can be used to control the placement location of the text. This is most useful when you want to actually add text to the asset. In most cases they are not used, but the options exist if needed. 

As described in the table, p3 is the paragraph index. When not set the first paragraph is used. Negative indexes count from the end of the story. 

p4 is the index word of the paragraph specified by p3. Again, if not specified, then the first word is used. Negative indexes count from the back of the paragraph.

Finally, p5 is the insertion point of the word of the paragraph. 0 is the before the first character. -1 is after the last character. 

To force something to the very end, use -1, -1, -1 as in this example: <&insert:(text,Is that the end?,-1,-1,-1)>