translate [options] [filename] | |
-h | print this help and exit |
-H,--help | print full documentation and exit |
-V,--version | print version and exit |
-c,--comma[=list separator] | string separating the regexps/replacements |
in the --old, --new and --pairs option; comma initially, empty by default | |
-f,--from=filename | file with tab-separated regexps/words |
-i,--inplace[=STRING] | edit files in place |
| if STRING given, save backups with STRING appended STRING must start with . or ~ | |
-l,--literal | take regexps as literal strings |
-m,--multi | allow multiline expressions |
-n,--new=repl[,repl...] | comma-separated replacements for the regexps |
-o,--old=re[,re...] | comma-separated regexps to be translated |
-p,--pairs=re,repl[,re,repl...] | comma-separated pairs of regexps and their replacements |
-t,--tab[=separator] | separator between regexps/words in --from file |
| tab initially and by default | |
--test | do a test run on the script's DATA section |
-v,--verbose | run verbosely |
-w,--word | only translate if matching string occurs |
| between word boundaries |
The words/fragments to be translated are given as an array of regular expression / translation (regexp,translation) pairs, and there are three ways to provide these pairs:
--old and --new options, where the --old option specifies a comma-separated list of
regexps and the --new option a list of
corresponding translations.
--pairs option, specifying a comma-separated
list of regexp,translation,regexp,translation... pairs
--from option, specifying a file containing
tab-separated regexp,translation pairs, one pair per line.
-h | |
| prints help information, then quits. | |
-H,--help | |
| prints full documentation, then quits. | |
-V,--version | |
| prints version and then quits. | |
--comma=string | |
If you need to translate from or to comma-containing strings, you can make translate to split strings on this <i>string</i>, instead of on comma's. If you set it to an empty string, or use it without an argument, no splitting is performed and the whole --old or --new string is translated from or to. If you use the --pairs option, it's argument will be split in characters, so that single characters can be converted into another set of single characters. | |
--inplace[=string] | |
Files to be translated are edited in place. If string is given, a copy of the original file is saved in a file with same name, with string appended; string must start with ~ or ., | |
--from=file | |
Specifies file to contain tab-separated word/fragment - translation pairs, one per line. With the --tab option the tab separation character can be changed into another character or string. Translations given on the command line are performed before those given in a file. | |
--literal | |
The regexps are interpreted as normal strings; without it, if you use the option --pairs␣'a+','b+', every occurrence of one or more a's will be translated into b+. The --literal option prevents this - it causes special characters in regexps to be escaped. | |
--multi | |
The expression may contain newline characters. This implies that the file is not handled line by line, but as a whole, which can cause mamory allocation problems for extremaly large files. With the --literal option, the sequence \n is seen as a newline - it will not be escaped. | |
--new=list | |
Comma separated list of translations for the words/fragments given with the --old option. If this list is shorter than the --old list, missing translations are set to the empty string, thus effectively deleting the corresponding words/fragments. String to be deleteted must then come at the end of the --old list, of course. Alternatively, you can explicitly use empty strings; for example, remove John and Mary and traslate Pete to Peter: translate --old=John,Pete,Mary --new=,Peter, or, using the --pairs option: translate --pairs=John,,Pete,Peter,Mary, | |
--old=list | |
Comma separated list of strings, which are interpreted as Ruby regexps to be replaced. When the --literal option is used, the strings are taken literally, not as regexps. | |
--pairs=list | |
Comma separated list of regexp,translation pairs: a merge of the --old and --new options. | |
--tab=string | |
| Word-pair separator string for word-pairs in the word-pair file. Default is the tab-character. | |
--test | |
| Run a test by interpreting the DATA section of the translate script. May be useful to see further examples. | |
--verbose | |
| print debugging information. | |
--word | |
translated texts must occur between word boundaries. Word boundaries are characters matching [a-zA-Z_] plus line boundaries; thus the command: translate --old=test --word will delete every word "test" but will leave a word like "testing" untouched. | |
\chapter to \section and \section to \subsection, saving the original in file.tex~:
translate --old='\section,\chapter' \
--new='\subsection,\section' \
--literal -i~ file.tex
Note the order in which the words are given; reversing the order would turn both \chapter and \section into \subsection. The --literal option was used here, because in a regexp, \s would be interpreted as a whitespace character, which is clearly not what we want here. As an alternative, the same result can be produced without the --literal option by escaping the regexp:
translate --old='\\section,\\chapter' \
--new='\\subsection,\\section' \
--inplace=.bak file.tex
Exchanging the occurrencies of John and Bill is a little tricky. The following would change both to John:
translate -o John,Bill -n Bill,John testfile
We need an extra pair here:
translate -o John,Bill,SomeWeirdString -n SomeWeirdString,John,Bill
In standard input, change every occurrence of "John, Bill" into "Anny" and write the result to standard output; the comma as a list separator must be changed, or eliminated:
translate --comma --old='John, Bill' --new=Anny
Do the same on many files, inplace, with no backup:
translate -o 'John, Bill' -n Anny -ci *.txt
Replace any two consecutive lines in file file.html containing:
</body> </html>
with six lines containing:
<!--#include virtual="tail1.inc" --> <!--#config timefmt="%Y-%m-%d %X %Z" --> <!--#echo var="LAST_MODIFIED" --> <!--#include virtual="tail2.inc" --> <!-- vim: tw=0 --> translate -lmi -o ' </body> </html> ' -n ' <!--#include virtual="tail1.inc" --> <!--#config timefmt="%Y-%m-%d %X %Z" --> <!--#echo var="LAST_MODIFIED" --> <!--#include virtual="tail2.inc" --> <!-- vim: tw=0 --> ' file.html