RTLCSS

RTLCSS is a framework for converting LTR CSS to RTL.

CSS Syntax

A CSS rule has two main parts: a selector, and one or more declarations:

The selector is normally the HTML element you want to style. Each declaration consists of a property and a value. The property is the style attribute you want to change. Each property has a value.

Powered by RTLCSS

• Semantic a UI component library implemented using a set of specifications designed around natural language. (RTL Version)
• AlertifyJS a javascript framework for developing pretty browser dialogs and notifications.
• WebEssentials2013 Web Essentials extends Visual Studio with a lot of new features that web developers have been missing for many years (now uses RTLCSS for converting LTR CSS to RTL).

Install

npm install rtlcss

Basic usage

var rtlcss = require('rtlcss');
var result = rtlcss.process("body { direction:ltr; }");
//result == body { direction:rtl; }

RTLCSS preserves original input formatting and indentations.

CLI

Convert LTR CSS files to RTL using the command line.

$ rtlcss input.css output.rtl.css

For usage and available options see CLI documentaion.

Supported CSS Properties (a-z)

background background-image background-position background-position-x border-bottom-left-radius border-bottom-right-radius border-color border-left border-left-color border-left-style border-left-width border-radius border-right border-right-color border-right-style border-right-width border-style border-top-left-radius border-top-right-radius border-width box-shadow clear cursor direction float left margin margin-left margin-right padding padding-left padding-right right text-align text-shadow transform transform-origin transition transition-property

Supported Processing Directives

When RTLing a CSS document, there are cases where its impossible to know if the property value should be mirrored or not! If the rule selector need to be changed! Or a none directional property have to be updated. In such cases, RTLCSS provides processing directives in the form of CSS comments, both standard /*rtl:...*/ and special/important /*!rtl:...*/ notations are supported.

Two sets of processing directives are available, on Rule and Declaration level.

Rule Level Directives:

Rule level directives are placed before the CSS rule.

Example

/*rtl:ignore*/
.code{
  direction:ltr;
  text-align:left;
}

Output

.code{
  direction:ltr;
  text-align:left;
}

Declaration Level Directives:

Declaration level directives are placed any where inside the declaration value.

Example

body{
  font-family:"Droid Sans", "Helvetica Neue", Arial/*rtl:prepend:"Droid Arabic Kufi", */;
  font-size:16px/*rtl:14px*/;
}

Output

body{
  font-family:"Droid Arabic Kufi", "Droid Sans", "Helvetica Neue", Arial;
  font-size:14px;
}

Advanced usage

// directly processes css and return a string containing the processed css
output = rtlcss.process(css [, options , rules, declarations, properties]);
output // processed CSS

// create a new RTLCSS instance, then process css with postcss options (such as source map)
result = rtlcss([options , rules, declarations, properties]).process(css, postcssOptions);
result.css // Processed CSS
result.map // Source map

// you can also group all configuration settings into a single object
result = rtlcss.configure(config).process(css, postcssOptions);
result.css // Processed CSS
result.map // Source map

Built on top of PostCSS, an awesome framework, providing you with the power of manipulating CSS via a JS API.

It can be combined with other processors, such as autoprefixer:

var processed = postcss()
  .use(rtlcss([options , rules, declarations, properties]).postcss)
  .use(autoprefixer().postcss)
  .process(css);

options (object)

stringMap (Array)

String map is a collection of map objects, each defines mapping between directional strings, it is used in selectors renaming and URL updates. The following is the default string map:

[
  {
    'name'    :	'left-right',
    'search'  :	['left', 'Left', 'LEFT'],
    'replace' :	['right', 'Right', 'RIGHT'],
    'options' : {
        'scope': options.swapLeftRightInUrl ? '*' : 'selector',
        'ignoreCase': false 
      }
  },
  {
    'name'    : 'ltr-rtl',
    'search'  : ['ltr', 'Ltr', 'LTR'],
    'replace' : ['rtl', 'Rtl', 'RTL'],
    'options' :	{
        'scope': options.swapLtrRtlInUrl ? '*' : 'selector',
        'ignoreCase': false
      }
  },
  {
    'name':'west-east',
    'search': ['west', 'West', 'WEST'],
    'replace': ['east', 'East', 'EAST'],
    'options' :	{
        'scope': options.swapWestEastInUrl ? '*' : 'selector',
        'ignoreCase': false
      }
  } 
]

To override any of the default maps, just add your own with the same name. A map object consists of the following:

The map options is optional, and consists of the following:

Example

// a simple map, for swapping "prev" with "next" and vice versa.
{
  "name"    : "prev-next",
  "search"  : "prev",
  "replace" : "next"
}

// a more detailed version, considering the convention used in the authored CSS document.
{
  "name"    : "prev-next",
  "search"  : ["prev", "Prev", "PREV"],
  "replace" : ["next", "Next", "NEXT"],
  options   : {"ignoreCase":false} 
}

rules (array)

Array of RTLCSS rule Processing Instructions (PI), these are applied on the CSS rule level:

Visit PostCSS to find out more about rule node.

Example

// RTLCSS rule processing instruction
{
  "name"        : "ignore",
  "expr"        : /\/\*rtl:ignore\*\//img,
  "important"   : true,
  "action"      : function (rule) {
                    return  true;
                  }
}

declarations (array)

Array of RTLCSS declaration Processing Instructions (PI), these are applied on the CSS declaration level:

Visit PostCSS to find out more about decl node.

Example

// RTLCSS declaration processing instruction
{
    "name"      : "ignore",
    "expr"      : /(?:[^]*)(?:\/\*rtl:ignore)([^]*?)(?:\*\/)/img,
    "important" : true,
    "action"    : function (decl) {
                    if (!config.preserveDirectives)
                        decl._value.raw = decl._value.raw.replace(/\/\*rtl:[^]*?\*\//img, "");
                    return true;
                  }
},

properties (array)

Array of RTLCSS properties Processing Instructions (PI), these are applied on the CSS property level:

Example

// RTLCSS property processing instruction
{
    "name"      : "direction",
    "expr"      : /direction/im,
    "important" : true,
    "action"    : function (prop, value) {
                    return { 'prop': prop, 'value': util.swapLtrRtl(value) };
                  }
}

Bugs and Issues

Have a bug or a feature request? please feel free to open a new issue .

Release Notes

• v1.4.0 [10 Oct. 2014]

  • CLI: Support processing a directory. see CLI documentation

• v1.3.1 [29 Sep. 2014]

  • Update README.md (typos).

• v1.3.0 [28 Sep. 2014]

  • New feature - String Maps. Add your own set of swappable strings, for example (prev/next).
  • Preserves lowercase, UPPERCASE and Capitalization when swapping left, right, ltr, rtl, west and east.

• v1.2.0 [26 Sep. 2014]

  • Support !important comments for directives (enables flipping minified stylesheets).

• v1.1.0 [26 Sep. 2014]

  • Upgrade to POSTCSS v2.2.5
  • Support flipping border-color, border-style and background-position-x

• v1.0.0 [24 Aug. 2014]

  • Upgrade to POSTCSS v2.2.1
  • Support flipping urls in '@import' rule.
  • Fix JSON parse error when configuration file is UTF-8 encoded.
  • Better minification.

• v0.9.0 [10 Aug. 2014]

  • New configuration loader.
  • CLI configuration can be set using one of the following methods:
    • Specify the configuration file manually via the --config flag.
    • Put your config into your projects package.json file under the rtlcssConfig property
    • Use a special file .rtlcssrc or .rtlcssrc.json

• v0.8.0 [8 Aug. 2014]

  • Fix source map generation.

• v0.7.0 [4 Jul. 2014]

  • Fix flipping linear-gradient.

• v0.6.0 [4 Jul. 2014]

  • Allow additional comments inside ignore/rename rule level directives.

• v0.5.0 [11 Jun. 2014]

  • Add CLI support.

• v0.4.0 [5 Apr. 2014]

  • Fix flipping transform-origin.
  • Update autoRename to search for all swappable words.

• v0.3.0 [5 Apr. 2014]

  • Support flipping rotateZ.
  • Fix flipping rotate3d.
  • Fix flipping skew, skewX and skewY.
  • Fix flipping cursor value.
  • Fix flipping translate3d.
  • Update flipping background horizontal position to treat 0 as 0%

• v0.2.1 [20 Mar. 2014]

  • Upgrade to POSTCSS v0.3.4

• v0.2.0 [20 Mar. 2014]

  • Support combining with other processors.
  • Support rad, grad & turn angle units when flipping linear-gradient
  • Fix typo in config.js

• v0.1.3 [7 Mar. 2014]

  • Fix missing include in rules.js

• v0.1.2 [5 Mar. 2014]

  • New option: minify output CSS.
  • Updated README.md

• v0.1.1 [4 Mar. 2014]

  • Initial commit.