Node.js Translation to Spanish - (1122 words) (Part-68)

Repository

Project Details

Node.js is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser.

Node.js came into existence when the original developers of JavaScript extended it from something you could only run in the browser to something you could run on your machine as a standalone application.

In simple words, it's an open source execution environment for developing web applications, which is event-based, it uses the V8 engine to provide an execution environment that compiles and executes JavaScript at a higher speed. It is possible to run Node.js without any restriction on Windows, Linux and Mac OS X.

It should be noted that it is NOT a server language, this means that it executes code, so it could be understood as an interpreter.

Contribution Specifications

Node.js is currently being translated into 33 languages. I'm contributing to translate it into the Spanish language.

So far, we have managed to translate 68% of the project!

Translation Overview

I started the translation of the folder N-api.md.

N-API (pronounced N as in the letter, followed by API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (ex V8) and is maintained as part of Node.js itself.

Previously, I briefly explained what an API is. If you want to see more information about it, you can visit this post.

The N-API is an API that ensures ABI stability across Node.js versions and different compiler levels. And an ABI (application binary interface) it's the interface between two program modules, it determines details such as how to call functions, in which binary format information should be passed from one program component to the next, or to the operating system in the case of a system call.

In this part of the module the envelope of objects and their functions is explained.

N-API offers a way to "wrap" C++ classes and instances so that the class constructor and methods can be called from JavaScript.

The [napi_define_class][] API defines a JavaScript class with constructor, static properties and methods, and instance properties and methods that correspond to the C++ class.
When JavaScript code invokes the constructor, the constructor callback uses [napi_wrap][] to wrap a new C++ instance in a JavaScript object, then returns the wrapper object.
When JavaScript code invokes a method or property accessor on the class, the corresponding napi_callback C++ function is invoked. For an instance callback, [napi_unwrap][] obtains the C++ instance that is the target of the call.

For wrapped objects it may be difficult to distinguish between a function called on a class prototype and a function called on an instance of a class. A common pattern used to address this problem is to save a persistent reference to the class constructor for later instanceof checks.

As an example of the work done, I will use the function napi_wrap belonging to this module:

English:

`napi_wrap`

Wraps a native instance in a JavaScript object. The native instance can be retrieved later using napi_unwrap().

When JavaScript code invokes a constructor for a class that was defined using napi_define_class(), the napi_callback for the constructor is invoked. After constructing an instance of the native class, the callback must then call napi_wrap() to wrap the newly constructed instance in the already-created JavaScript object that is the this argument to the constructor callback. (That this object was created from the constructor function's prototype, so it already has definitions of all the instance properties and methods.)

Typically when wrapping a class instance, a finalize callback should be provided that simply deletes the native instance that is received as the data argument to the finalize callback.

The optional returned reference is initially a weak reference, meaning it has a reference count of 0. Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid.

Caution: The optional returned reference (if obtained) should be deleted via [napi_delete_reference][] ONLY in response to the finalize callback invocation. (If it is deleted before then, then the finalize callback may never be invoked.) Therefore, when obtaining a reference a finalize callback is also required in order to enable correct proper of the reference.

Spanish:

`napi_wrap`

Envuelve una instancia nativa en un objeto de JavaScript. La instancia nativa puede ser recuperada luego utilizando napi_unwrap().

Cuando un código de JavaScript invoca un constructor para la clase que fue definida utilizando napi_define_class(), el napi_callback para el constructor es invocado. Luego de construir una instancia de la clase nativa, la callback debe llamar entonces a napi_wrap() para envolver a la instancia recién construida en el ya creado objeto de JavaScript que es el argumento this de la callback del constructor. (Ese objeto this fue creado desde el prototype de la función del constructor, entonces ya tiene definiciones de todas las propiedades y métodos de instancia.)

Normalmente, al envolver una instancia de clase, se debe proporcionar un callback de terminación que simplemente elimine la instancia nativa que se recibe como el argumento data para la callback de terminación.

La referencia opcional devuelta es, inicialmente, una referencia débil, lo que significa que tiene una cuenta de referencia de 0. Normalmente, esta cuenta de referencia se incrementará temporalmente durante operaciones asíncronas que requieran que la instancia permanezca válida.

Precaución: La referencia opcional devuelta (si se obtiene) debe ser eliminada a través de [napi_delete_reference][] SOLO en respuesta a la invocación de la callback de terminación. (Si es eliminada antes de eso, entonces puede que la callback de terminación nunca sea invocada.) Por lo tanto, cuando se obtiene una referencia, también se requiere una callback de terminación para permitir la apropiada corrección de la referencia.

Note: This API may modify the prototype chain of the wrapper object. Afterward, additional manipulation of the wrapper's prototype chain may cause napi_unwrap() to fail.